OAuth 2.0 — Authorization Code grant + PKCE

Grant user-on-behalf — usuário humano vai ao provider, autoriza o Lefia, volta com code. RFC 6749 §4.1 + PKCE RFC 7636 (S256).

Quando usar

• Acessar dados em nome de um usuário real (Google Workspace, Microsoft 365 pessoal, GitHub, etc.)
• Provider exige consent screen e refresh_token de longa duração
• Conformidade que proíbe Client Credentials (provider só libera escopo via auth user)

Como configurar

No form REST, escolha Autenticação = oauth2_auth_code e preencha:

Fluxo após salvar

1. Salve a conexão (sem clicar em "Testar" ainda — não tem token).
2. Clique no botão "Connect" no card da integração.
3. Um popup abre com a tela de consent do provider.
4. Após autorizar, o popup fecha sozinho e a UI atualiza com toast "Conexão autorizada".
5. Daí em diante, "Testar" e o pipeline de mensagens usam o token cacheado.

Refresh automático

Authorization Code é o único grant que devolve refresh_token. O Lefia:

• Cacheia access_token + refresh_token criptografados em oauth_tokens.
• Quando access_token expira: tenta refresh transparentemente.
• Se refresh falhar (refresh revogado / expirado): pipeline retorna erro "Reconecte a conexão" — botão "Reconectar" aparece pro user passar pelo redirect de novo.

Segurança

• State CSRF + PKCE S256 obrigatórios. State persistido em oauth_authorization_states com TTL 15min e used_at anti-replay.
• Callback valida origem, expiração e single-use antes de trocar code.
• Refresh tokens criptografados com a mesma key dos credentials (AES-256-GCM).

Limitações

• Provider deve registrar o Redirect URI exatamente como https://lefia.ai/api/oauth/callback (ou o custom que você configurar).
• Popup blocker pode bloquear o flow — peça pro user permitir popups do site.
• Tokens são per-connection, não compartilhados entre conexões.

Tickets relacionados

• #195 implementação completa (PKCE, callback, refresh, UI Connect button).