auth

O submódulo Auth gerencia todas as fases do ciclo de vida da identidade do usuário: troca de credenciais, emissão de tokens de sessão, desafios de autenticação multifator, recuperação de senha e encerramento de sessão. É o ponto de entrada para toda a autenticação voltada ao usuário e o guardião de todo recurso protegido na plataforma.

O login retorna um JWT access token de curta duração usado no cabeçalho Authorization: Bearer para endpoints protegidos e, opcionalmente, um refresh token de longa duração. O refresh token pode ser trocado por um novo par access/refresh sem nova autenticação, permitindo continuidade de sessão transparente entre sessões de navegador e aplicativos móveis. O logout invalida o refresh token no servidor, garantindo que a sessão termine mesmo que o access token ainda não tenha expirado naturalmente.

O HedHog oferece três canais de MFA. O TOTP funciona com qualquer aplicativo autenticador compatível com os padrões (Google Authenticator, Authy, 1Password). O OTP por e-mail envia um código de seis dígitos para o endereço de e-mail verificado do usuário. O WebAuthn usa a Web Authentication API para aproveitar chaves de segurança em hardware, Face ID, Touch ID ou Windows Hello. Quando o MFA está habilitado, o fluxo de login padrão responde com um mfaToken pendente em vez de uma sessão completa — o cliente precisa enviar o código correto pelo endpoint de verificação correspondente para receber o access token final. Os códigos de recuperação servem como backup quando o dispositivo de MFA principal está indisponível.

O fluxo de esqueci-a-senha tem duas etapas: um código de uso único e com prazo limitado é enviado ao e-mail cadastrado (POST /auth/forgot), e esse código é então enviado junto com a nova senha (POST /auth/forgot-reset). A cerimônia de asserção WebAuthn segue o mesmo modelo de duas etapas — gerar as opções e, em seguida, verificar a resposta assinada pelo autenticador.

O autocadastro via POST /auth/signup está disponível para plataformas de registro aberto. Para implantações somente por convite ou provisionadas por administradores, esse endpoint pode ser restringido por permissões em nível de rota sem alterar o código.