Aparência
Login em Duas Etapas (2FA)
Segundo fator de autenticação opcional, escolhido pelo próprio usuário nas configurações da conta. Padrão: vazio — nenhuma validação extra, até o usuário ativar e confirmar um método.
Métodos ativáveis (novos): SMS ou Google Authenticator (TOTP) — TwoFactorMethod::selectable(). email continua existindo como valor válido do enum (login/reenvio de quem já tinha ativado antes dessa restrição continuam funcionando normalmente), mas não é mais oferecido em POST account/two-factor/setup (§3).
SMS só pode ser ativado depois que o telefone é verificado — fluxo novo de verificação de telefone (§3.1), independente do 2FA em si.
Envio de código (e-mail e SMS) é sempre SÍNCRONO — nunca fila/job. A chamada ao provedor (SES/AWS Notify) acontece dentro da própria requisição e só é considerada "enviada" depois que o provedor confirma; falha vira TwoFactorException/PhoneVerificationException (nunca vaza a exceção crua). Ver TwoFactorService::sendEmailCode()/sendSmsCode().
Implementado em App\Services\TwoFactor\TwoFactorService (orquestração) + App\Services\TwoFactor\TotpService (TOTP puro, RFC 6238, sem dependência de Composer), App\Services\Phone\PhoneVerificationService (verificação de telefone), App\Http\Controllers\Access\AuthController (desafio de login), App\Http\Controllers\Access\TwoFactorSettingsController (ativar/desativar nas configurações) e App\Http\Controllers\Access\PhoneVerificationController (verificar telefone).
1. Modelo de dados
users (colunas novas)
two_factor_method(string, nullable):null|email|sms|google(emailsó chega aqui por ativações antigas — não é mais selecionável).two_factor_secret(text, nullable, hidden na serialização): segredo TOTP em base32 — só preenchido paragoogle, só depois de confirmado.two_factor_confirmed_at(timestamp, nullable).phone_verified_at(timestamp, nullable, nova): preenchido só porPhoneVerificationService::confirm(), junto comphonena mesma atualização.User::boot()zera automaticamentephone_verified_atsempre quephonemuda sem quephone_verified_attambém mude na mesma gravação — garante que "verificado" sempre se refere ao número atual, mesmo quephoneseja alterado por outro caminho no futuro (edição de perfil, por exemplo).User::hasVerifiedPhone(): bool.
2FA só é exigido no login se as duas colunas estiverem preenchidas (User::hasTwoFactorEnabled(): two_factor_method !== null && two_factor_confirmed_at !== null). startSetup() (§3) não toca em nenhuma das duas — só confirmSetup() as preenche, depois do código validado — então um setup começado e nunca confirmado nunca deixa o usuário travado fora da própria conta.
two_factor_challenges (tabela nova)
Um registro por vez, por user_id + purpose (o service sempre apaga qualquer desafio anterior do mesmo par antes de criar um novo):
| Coluna | Uso |
|---|---|
token | Opaco, devolvido ao cliente — nunca o id numérico. |
purpose | login (depois da senha), setup (ativar nas configurações) ou phone_verification (verificar telefone antes de ativar SMS). |
method | email | sms | google. |
code_hash | Hash (Hash::make) do código de 6 dígitos — só e-mail/SMS/verificação de telefone. |
pending_secret | Segredo TOTP recém-gerado, só purpose=setup + method=google — não vai para users até confirmar. |
pending_phone | Telefone normalizado aguardando confirmação, só purpose=phone_verification — só vira users.phone depois do código certo. |
device_name | Só purpose=login — replica a bifurcação dashboard_sass/UserAccount de AuthController na hora de emitir o token final. |
attempts | Máx. 5 (TwoFactorService::MAX_ATTEMPTS) — estourou, desafio é apagado e o cliente precisa recomeçar. |
expires_at | 10 minutos (TwoFactorService::CODE_TTL_MINUTES). |
2. Fluxo de login
POST auth/login { email, password }
→ sem 2FA confirmado: mesmo token de sempre (nada muda)
→ com 2FA confirmado: { two_factor_required: true, method, challenge_token, expires_at }
POST auth/login/two-factor/verify { challenge_token, code } (throttle 10/min)
→ código certo: mesmo token que auth/login devolveria sem 2FA
→ código errado/expirado: 422 { error: "..." }
POST auth/login/two-factor/resend { challenge_token } (throttle 5/min)
→ só para email/sms — reenvia um código novo, zera as tentativas
→ google: 422 (o app já gera um código novo sozinho a cada 30s)AuthController::issueLoginResponse() (privado) concentra a emissão do token — extraído do login() original, reaproveitado por verifyTwoFactor(), garantindo que os dois caminhos (com e sem 2FA) emitam exatamente o mesmo formato de resposta.
3. Fluxo de configuração (account/two-factor*, autenticado)
GET account/two-factor
→ { method, confirmed, email, phone, phone_verified } (nunca o segredo TOTP)
POST account/two-factor/setup { method: 'sms' | 'google' }
→ sms/google só (email não é mais aceito aqui — 422 "Método não
disponível para ativação. Escolha SMS ou Google Authenticator." —
TwoFactorMethod::selectable())
→ sms: manda o código na hora, devolve { challenge_token }
→ google: gera um segredo novo (ainda não salvo no usuário), devolve
{ challenge_token, secret, otpauth_uri } — o front renderiza o QR Code
a partir de otpauth_uri (client-side; o segredo nunca sai para um
serviço externo de geração de QR)
POST account/two-factor/confirm { challenge_token, code }
→ código certo: ativa (two_factor_method + two_factor_secret [google] +
two_factor_confirmed_at = now())
→ código errado/expirado: 422
DELETE account/two-factor { current_password }
→ exige a SENHA ATUAL, não um código de 2FA — evita travar quem perdeu
acesso ao próprio método (celular perdido, número trocado, etc.)sms exige que o usuário já tenha o telefone verificado (User::hasVerifiedPhone(), 422 "Verifique seu telefone antes de ativar a verificação por SMS." se não tiver) — ver §3.1 para o fluxo de verificação.
3.1 Verificação de telefone (account/phone-verification*, autenticado)
Pré-requisito para ativar 2FA por SMS — mas é um fluxo independente (o telefone pode ser verificado sem nunca ativar 2FA). Reaproveita a tabela two_factor_challenges com purpose=phone_verification (App\Services\Phone\PhoneVerificationService).
POST account/phone-verification/start { phone } (throttle 5/min)
→ normaliza o telefone (só dígitos, mínimo 10), manda o código por SMS
na hora (Notify, mesmo caminho do 2FA) — NÃO altera users.phone ainda
→ falha ao enviar: 422, desafio é apagado (não fica pendência órfã)
POST account/phone-verification/confirm { code } (throttle 10/min)
→ código certo: grava phone + phone_verified_at juntos (User::boot()
exige isso — ver §1) e apaga o desafio
→ código errado: 422, incrementa attempts (máx. 5, depois disso o
desafio é apagado e é preciso chamar /start de novo)
→ expirado/sem desafio pendente: 422
POST account/phone-verification/resend (throttle 5/min)
→ reenvia para o mesmo pending_phone do desafio atual (chama /start de
novo internamente) — 422 se não houver verificação pendenteValidação do código/estado é toda no backend (PhoneVerificationService) — o front só conduz a interface (campos de telefone/código, contagem de tentativas/expiração vindas dos erros 422).
O envio em si é via AWS End User Messaging Notify (App\Services\AwsEndUserMessagingSmsService::sendVerificationCode(), Aws\PinpointSMSVoiceV2\PinpointSMSVoiceV2Client::sendNotifyTextMessage()) — um template pré-aprovado da AWS (texto/idioma já prontos, ex.: notify-code-verification-portuguese-brazil-007), só o código é substituído. Não confundir com "Amazon SNS → Text messaging (SMS)" (Aws\Sns\SnsClient::publish()) — são dois produtos AWS diferentes para mandar SMS, cada um com seu próprio sandbox/verificação de número/origem; usar o errado (SNS) parece funcionar (a chamada tem sucesso) mas nunca entrega.
Exigiu atualizar aws/aws-sdk-php — a versão instalada quando o End User Messaging "cru" (sendTextMessage) foi implementado não tinha nenhuma operação *Notify* ainda (recurso recente da AWS); composer update aws/aws-sdk-php --with-dependencies trouxe pra 3.397.0, dentro da mesma faixa ^3.316 do composer.json (sem mudança de constraint).
Reaproveita as credenciais AWS já usadas para S3 (config/services.php → aws_sms) — a chave IAM precisa também ter sms-voice:SendNotifyTextMessage liberado. AWS_SMS_NOTIFY_CONFIGURATION_ID (.env) é obrigatório — o ID/ARN de uma configuração Notify já criada no console (use case "Code verification"), com status ACTIVE. AWS_SMS_NOTIFY_TEMPLATE_ID é opcional (default notify-code-verification-portuguese-brazil-007). AWS_SMS_ORIGINATION_IDENTITY/AWS_SMS_REGION continuam existindo só pro envio "cru" de teste (sms:test sem --notify) — o 2FA não usa mais. Falha no envio (credenciais ausentes, configuração não encontrada, número inválido, etc.) vira TwoFactorException — nunca vaza a exceção crua da AWS pro usuário.
Testar a integração sem passar pelo login/2FA:
php artisan sms:test 11987654321 --notifyManda um código de teste pelo mesmo caminho que o 2FA usa de verdade, mostra o erro exato da AWS se falhar, e confirma se o número de destino já está verificado (ver abaixo). Se AWS_SMS_NOTIFY_CONFIGURATION_ID estiver vazio, lista as configurações Notify e os templates já disponíveis na conta (com status/idioma/países) em vez de tentar enviar às cegas. Sem --notify, o comando testa o envio "cru" (sendTextMessage + AWS_SMS_ORIGINATION_IDENTITY) — útil pra isolar se o problema é geral (credenciais/conta) ou específico do Notify (configuração/template).
"Enviou com sucesso mas não chegou no celular": quase sempre é o número de destino não estar verificado — contas novas de End User Messaging só entregam pra destinos verificados manualmente, mesmo que o envio retorne sucesso. sms:test checa isso sozinho depois de um envio "bem-sucedido". Pra verificar um número direto do terminal (a AWS manda um código de verdade por SMS, você confirma na hora):
php artisan sms:test 11987654321 --verifyManual, no console AWS: End User Messaging → Verified destination phone numbers (verificar o número) — ou pedir saída do modo restrito nas configurações da conta, se disponível para a região.
4. TOTP (Google Authenticator) — TotpService
Implementação própria, em PHP puro (HMAC-SHA1, 6 dígitos, período de 30s — o padrão que Google Authenticator/Authy/1Password esperam), em vez de uma dependência de Composer (pragmarx/google2fa etc.): adicionar uma lib exigiria rodar composer update para regravar o composer.lock, indisponível neste ambiente (sem PHP instalado).
Algoritmo conferido manualmente contra o vetor de teste oficial da RFC 6238 (Apêndice B — segredo ASCII "12345678901234567890", T=59 → código de 6 dígitos 287082, os últimos 6 dígitos do valor de 8 dígitos que o apêndice mostra) — reproduzido em tests/Unit/TotpServiceTest.php e também verificado à parte em Python (hmac/hashlib) antes de escrever a versão PHP; os dois batem com o vetor oficial.
verify() aceita ±1 período (30s) de tolerância, para relógios de celular levemente dessincronizados.
5. O que não foi feito
- Recuperação de conta: se o usuário perder acesso ao método de 2FA (celular com o Authenticator, número de SMS, e-mail), não há fluxo de auto-recuperação (códigos de backup, por exemplo) — hoje só dá para desativar manualmente no banco (
users.two_factor_method = nulletc.), via suporte. Não foi pedido nesta etapa. - Front-end:
fastgivr-portal— tela de login com a segunda etapa, tela de verificação de telefone e a tela de configuração (ativar SMS/Google, confirmar, desativar) no Perfil, comsmshabilitado no seletor de método (hoje desabilitado no front até essa etapa ser concluída) eemailremovido das opções de ativação.