feat(auth): implementar Device Fingerprinting e gestão de sessões ativas (#158)

[NdondaDaniel2020]

📌 Descrição & Motivação

Esta Pull Request implementa Device Fingerprinting e Gestão Avançada de Sessões Ativas do Usuário, permitindo rastrear os dispositivos conectados (device_name, ip_address, user_agent, last_seen_at) na emissão e renovação de refresh tokens, e disponibiliza endpoints REST para que o usuário visualize e encerre remotamente suas sessões em outros dispositivos.

Closes #158

---

🛠️ O que foi feito?

1. Banco de Dados & Modelos (SQLAlchemy & Alembic)

• Adicionadas as colunas ip_address, user_agent, device_name, location e last_seen_at no modelo RefreshToken (app/models/refresh_token.py).
• Todas as novas colunas são nullable=True para garantir 100% de compatibilidade retroativa com tokens existentes.
• Coluna last_seen_at mantida sem índice para viabilizar atualizações em memória HOT (Heap-Only Tuples) no PostgreSQL sob alta concorrência.
• Criada migração Alembic segura: migrations/versions/12a7942e3290_add_device_fingerprinting_to_refresh_.py.

2. Utilitário de Device Fingerprinting (app/core/device.py)

• extract_client_ip(): Extração segura de IP priorizando headers de proxy reverso (X-Forwarded-For, X-Real-IP).
• parse_user_agent(): Parser determinístico e de alta performance em memória para identificar SO (macOS, iOS, Windows, Linux, Android) e Navegador (Chrome, Safari, Firefox, Edge, Opera, Postman, cURL).

3. Repositório & Camada de Serviços

• RefreshTokenRepository: Métodos create() com metadados, list_active_by_user(), revoke_by_jti_and_user() e revoke_other_sessions().
• app/services/session_service.py: Camada desacoplada para listagem, revogação unitária e revogação em massa das sessões do usuário.
• app/services/auth_service.py: Passagem de metadados em create_token_pair(), authenticate_mfa_challenge() e propagação de metadados no refresh_tokens().

4. Endpoints REST de Usuário

• GET /api/users/me/sessions: Retorna a lista de sessões ativas do usuário com metadados legíveis de dispositivo.
• DELETE /api/users/me/sessions/{jti}: Revoga remotamente uma sessão ativa específica.
• DELETE /api/users/me/sessions: Revoga todas as outras sessões ativas do usuário.

---

📦 Commits Atômicos

1202cef feat(db): adicionar colunas de device fingerprinting no model e migracao alembic
cd1e3c4 feat(auth): adicionar utilitario de parser de user-agent e schemas de sessao
bbc7560 feat(sessions): implementar listagem e revogacao de sessoes no repositorio e servico
21c8005 feat(api): disponibilizar endpoints de gerenciamento de sessoes em /users/me/sessions
6ca965b test(sessions): adicionar testes unitarios e de integracao para device fingerprinting e sessoes

---

🧪 Testes & Validação

• Testes Automatizados da Feature: tests/test_device_fingerprinting.py (4/4 passed).
• Suíte Completa de Testes: uv run pytest --ignore=tests/test_db_connection.py (447 passed).
• Qualidade de Código: uv run ruff check e uv run ruff format --check 100% aprovados.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
auth	Ready	Preview	Aug 30, 2026 2:26am