Autenticação & Integrações OAuth 2.0 (Google, LinkedIn & GitHub)

🔐 Autenticação, OAuth Dinâmico & Trilhas de Auditoria

O Academic Companion (acad) adota uma arquitetura de autenticação moderna e segura, projetada para garantir zero vazamento de credenciais via JavaScript (XSS) através de cookies HttpOnly, suporte nativo a login federado institucional e de desenvolvedor via Google OAuth 2.0, LinkedIn OpenID e GitHub OAuth, além de gerenciamento dinâmico de credenciais criptografadas no PostgreSQL e auditoria completa de acessos.

🛡️ 1. Princípios de Segurança & Gestão de Sessão

Cookies HttpOnly vs. LocalStorage

Para evitar vulnerabilidades de roubo de sessão através de ataques Cross-Site Scripting (XSS):

Os tokens JWT (accessToken e refreshToken) são emitidos como cookies HttpOnly, com atributos SameSite=Lax (ou Strict) e Secure=true em ambiente de produção (HTTPS).
O frontend discente e administrativo nunca tem acesso direto à string do token, eliminando riscos de leitura maliciosa no DOM.
As rotas protegidas enviam automaticamente os cookies para a API backend (apps/backend) por meio de credentials: 'include'.

⚙️ 2. Credenciais OAuth Dinâmicas no Banco de Dados

Diferente de abordagens estáticas que exigem alteração manual de arquivos .env e reinicialização de containers em produção, o sistema suporta configuração dinâmica de OAuth:

As chaves de cliente (clientId), segredos (clientSecret), URIs de callback (redirectUri) e flags de ativação (enabled) são armazenadas com categoria AUTH_OAUTH na tabela SystemSetting.
O endpoint administrativo GET /api/admin/auth-config e PUT /api/admin/auth-config permite que superusuários configurem Google, LinkedIn e GitHub diretamente pela interface web (/acessos), com máscara de segurança (******).
O endpoint público GET /api/auth/providers informa ao frontend quais botões de login social devem ser renderizados.

🌐 3. Provedores Federados (Google, LinkedIn & GitHub)

Google OAuth 2.0

Suporta autenticação com contas institucionais (como @ufsm.br) e contas pessoais Google.

LinkedIn OpenID Connect

Permite identificação através do perfil profissional do LinkedIn e habilita a publicação automática de conquistas acadêmicas.

GitHub OAuth 2.0

Projetado para estudantes de cursos de tecnologia, computação e engenharia. Resolve automaticamente e-mails primários verificados mesmo quando configurados como privados no GitHub (https://api.github.com/user/emails).

PGI-PROA & Dorneles Identity Provider (SSO Central)

O PGI-PROA (sistema de gestão de projetos e equipes) opera integrado ao Dorneles IdP (Ory Hydra v2.2.0) com escopos pgi:read e pgi:admin. O Academic Companion consome os projetos em modo estritamente Leitor (Dashboard):

Disparo de Sincronização: Acionado sob demanda (on-load ao carregar a página com cache inteligente de 5 minutos, ou clique explícito no botão “Sincronizar”). Sem jobs de background (cron) para evitar consumo desnecessário.
Ação Rápida: Botão “Abrir no PGI” disponível diretamente ao lado de sincronizar, direcionando o estudante para a respectiva visualização no PGI-PROA (:5175).
Isolamento de Domínios: Os TimeLogs do PGI-PROA não geram memórias acadêmicas (AcademicMemory), sendo totalizados estritamente no campo analítico metadata.pgiProaTotalMinutes.

Endpoints Oficiais de Autenticação & Integrações

Provedor	Método	Rota	Descrição
Público	`GET`	`/api/auth/providers`	Retorna mapa booleano de provedores habilitados
Google	`GET`	`/api/auth/google/url`	URL de consentimento com state anti-CSRF
Google	`POST`	`/api/auth/google/callback`	Validação do código de autorização Google
LinkedIn	`GET`	`/api/auth/linkedin/url`	URL de consentimento do LinkedIn
LinkedIn	`POST`	`/api/auth/linkedin/callback`	Validação do código de autorização LinkedIn
GitHub	`GET`	`/api/auth/github/url`	URL de consentimento do GitHub
GitHub	`POST`	`/api/auth/github/callback`	Validação do código e criação/vínculo de conta
Dorneles IdP	`GET`	`/api/auth/dorneles/url`	URL de autorização OIDC com state anti-CSRF
Dorneles IdP	`GET`	`/api/auth/dorneles/login`	Endpoint de redirecionamento 302 direto para login SSO
Dorneles IdP	`POST`	`/api/auth/dorneles/callback`	Troca de `code` por tokens e emissão de sessão HttpOnly
PGI-PROA	`GET`	`/api/integrations/pgi-proa/status`	Status de conexão e última sincronização
PGI-PROA	`GET`	`/api/integrations/pgi-proa/auth-url`	URL de autenticação via Dorneles IdP
PGI-PROA	`POST`	`/api/integrations/pgi-proa/sync`	Sincronização de projetos (suporta `?force=true`)
PGI-PROA	`DELETE`	`/api/integrations/pgi-proa`	Desconexão do workspace PGI-PROA

🏛️ 3.1. Dorneles Identity Provider (SSO Central do Ecossistema)

O Academic Companion adota o Dorneles IdP (id.dorneles.dev) como provedor primário e oficial de identidade unificada:

Ory Hydra (oauth.dorneles.dev): Servidor OAuth2 / OIDC certificado que emite tokens criptografados e gerencia fluxos de consentimento e login challenge.
Ory Kratos (auth.dorneles.dev): Gerenciador de identidade e perfis, autenticação multifator (MFA) e recuperação de senhas.
Topologia de Produção:
- acad.dorneles.dev (Frontend) redireciona via DORNELES_LOGIN_URL para api-acad.dorneles.dev/api/auth/dorneles/login.
- O backend constrói a URL de autorização (oauth.dorneles.dev/oauth2/auth) com escopos openid profile email offline_access academic:read academic:write e redireciona (HTTP 302).
- O Ory Hydra redireciona o navegador para a UI oficial em id.dorneles.dev/login?login_challenge=....
- Após a autenticação/cadastro, o Hydra redireciona de volta para acad.dorneles.dev/auth/dorneles/callback?code=....
- O backend do acad troca o code pelo access token via Hydra Token Endpoint (oauth.dorneles.dev/oauth2/token), provisiona ou atualiza o perfil do discente e emite os cookies de sessão segura accessToken e refreshToken HttpOnly.

📊 4. Monitoramento de Acessos & Auditoria (Admin)

No painel administrativo (apps/admin, rota /acessos), administradores acompanham em tempo real:

KPIs do Dia: Total de logins hoje, acessos divididos por provedor (Google, LinkedIn, GitHub, E-mail tradicional) e taxa de falhas.
Trilha Detalhada: Cada tentativa de autenticação registra autor/usuário, endereço IP, dispositivo/navegador (User-Agent), status (Sucesso/Falha) e timestamp.
Filtros Avançados: Busca textual por e-mail ou IP, filtragem por método de login e status de concessão.

🎁 5. Onboarding Automático & Carteira de Tokens

Ao entrar via OAuth pela primeira vez (Google, LinkedIn ou GitHub):

Um registro de usuário (User) é criado com papel STUDENT.
O perfil acadêmico (StudentProfile) é provisionado automaticamente.
A carteira (UserWallet) é provisionada com 50 tokens gratuitos de boas-vindas com transação do tipo WELCOME_BONUS.
Uma notificação interna de boas-vindas é enviada à central de notificações do estudante.