Modo sudo
Provar que a pessoa ainda está no teclado, sem desconectá-la.
Uma sessão diz quem entrou. Ela não diz quem está no teclado agora. O modo sudo é uma janela curta em que isso acabou de ser provado de novo, e existe para que uma sessão roubada ou emprestada não consiga mudar silenciosamente as coisas que protegem uma conta.
Quais ações exigem
Isso é configuração, não algo fixo no SDK. Um ambiente nomeia os grupos que quer proteger:
manage_mfaCadastrar, remover fatores, ler códigos de recuperação.manage_credentialsMudanças de credenciais.manage_grantsConvidar, revogar, bloquear, mudar permissões.manage_identitiesAdicionar ou remover um e-mail ou telefone.manage_sessionsRevogar sessões.manage_passwordsTrocar a senha.Junto delas, em Segurança & Proteção, Habilitar modo Sudo é a chave geral e Tempo de expiração define quanto tempo uma elevação dura.
Como é configuração, não fixe no código quais das suas chamadas precisam de sudo. Um ambiente pode ligar um grupo mês que vem e o seu código já deveria lidar com isso. A próxima seção mostra como.
Reaja ao evento, não tente prever
O SDK emite sudo-required quando uma chamada é rejeitada por esse motivo, então
um handler cobre todas as chamadas protegidas da aplicação:
nulvless.auth.on('sudo-required', async () => {
await nulvless.auth.sessions.sudo(); // envia o código
openSudoPrompt(); // sua UI coleta
});Por baixo, é um 403 com o código protected_action_denied. Se você trata erros
direto em vez de por eventos, case com esse código.
As duas formas de satisfazer
As duas começam igual — sessions.sudo() envia um código e devolve um desafio. O
que muda é onde você gasta o código.
await nulvless.auth.sessions.sudo();
const { data } = await nulvless.auth.sessions.sudoVerify({ code });
// data.sudo.expires_in → segundos que a janela duraA sessão é reemitida com sudo ativo e guardada automaticamente. Toda chamada protegida passa até a janela fechar.
Certo quando o usuário vai fazer várias coisas sensíveis em sequência — uma tela de configurações de segurança, por exemplo.
O nonce é o código
nonce não é um token separado que você busca. É o código que o usuário digitou,
resolvido contra o desafio de sudo já pendente para a sessão dele. É de uso
único, vai dentro dos params e não nas options, e viaja no header
nlv-sudo-nonce.
Escolhendo o método
O sudo() aceita um método opcional:
await nulvless.auth.sessions.sudo('email_otp');Os valores aceitos são totp, email_otp e sms_otp. Omita e a plataforma
escolhe, do mesmo jeito que faz num desafio de MFA.
Verificando sem fazer nada
const { error } = await nulvless.auth.sessions.checkSudo();
if (error) startSudoFlow();Útil para decidir se uma tela de configurações deve pedir confirmação já na entrada, em vez de deixar o primeiro clique destrutivo falhar.
No seu próprio servidor
A sua API pode exigir a mesma comprovação para rotas que a plataforma desconhece — apagar um workspace, rotacionar uma chave sua.
O navegador obtém o código exatamente como acima e o envia; o seu handler apenas repassa para a chamada protegida:
app.delete('/keys/:id', requireAuth, async (req, res) => {
const { error } = await nulvless.auth.sessions.revoke({
id: req.params.id,
nonce: req.headers['nlv-sudo-nonce'] as string,
});
if (error) return res.status(403).json({ error });
res.status(204).end();
});O que sudo não é
Não é verificação de permissão. O sudo responde "esta pessoa ainda está aqui?", não "ela pode fazer isso?" — um usuário com a sessão recém-elevada continua falhando numa verificação de autorização para a qual ele não tem o grant. Os dois rodam de forma independente, e uma ação sensível normalmente quer os dois.