auth.factors
Cadastrar métodos multifator e gerenciar códigos de recuperação.
Fatores são o que transforma uma entrada numa entrada em dois passos. Este
namespace é a metade de gestão — um usuário autenticado configurando ou
removendo os próprios métodos. A outra metade, o desafio que aparece na entrada
depois, é o auth.challenges.
Toda chamada aqui, exceto enable, é protegida por sudo sob manage_mfa. Isso
é deliberado: uma sessão roubada não pode conseguir remover o segundo fator que
a teria barrado.
list
list() → AuthMethod[]
Os fatores configurados para o usuário atual.
const { data: factors } = await nulvless.auth.factors.list();idstringOptionalO que o unenroll recebe.
typeMFAMethodRequiredtotp, sms_otp, email_otp ou recovery_codes.
namestringOptionalO que a pessoa chamou de nome no cadastro — "Telefone do trabalho", "1Password".
statusAuthFactorStatusRequiredconfiguredConfigurado e utilizável.not_configuredDisponível neste ambiente, não configurado.created_atstringOptionalUm resultado vazio depois da entrada é o sinal para conduzir a pessoa pelo cadastro de um fator, que é como você atende um ambiente que exige MFA.
enroll
enroll({ type, name, phone, nonce }) → FactorEnrollment
Começa a configurar um fator. Nada está ativo ainda.
const { data } = await nulvless.auth.factors.enroll({
type: 'totp',
name: 'Meu autenticador',
nonce: code,
});
// data.url → renderize como QR code
// data.secret → entrada manualtypeMFAMethodRequiredtotpUm app autenticador. Devolve um secret e uma URL de provisionamento.sms_otpCódigos por SMS.email_otpCódigos por e-mail.recovery_codesO conjunto imprimível de reserva.namestringOptionalAparece na lista de fatores da pessoa. Vale coletar — quem tem dois autenticadores não consegue distinguir de outro jeito.
phonePhoneOptionalSó para sms_otp. O número que recebe os códigos — pode ser diferente do
telefone do usuário. Por padrão, usa o telefone do usuário. O mesmo número não
pode ser fator SMS duas vezes (mfa_phone_already_enrolled).
noncestringOptionalConfirmação de sudo.
Um usuário pode ter até 10 apps autenticadores e fatores SMS somados
(mfa_factors_limit_reached além disso; o ambiente pode reduzir esse limite), e um único fator de e-mail e conjunto de códigos de recuperação.
Devolve FactorEnrollment:
tokenstringRequiredDe vida curta. Leve-o até o enable.
secretstringOptionalSó para TOTP. O secret compartilhado, para quem digita à mão.
urlstringOptionalSó para TOTP. Uma URL de provisionamento — renderize direto como QR code em vez de montar uma a partir do secret.
enable
enable({ token, code }) → null
Ativa um cadastro pendente provando que o dispositivo funciona.
await nulvless.auth.factors.enable({
token: data.token,
code: firstCodeFromTheApp,
});tokenstringRequiredVindo do enroll.
codestringRequiredO primeiro código que o dispositivo da pessoa produz.
Até isso dar certo, o fator não existe. Um cadastro abandonado deixa a conta exatamente como estava — não há estado meio-habilitado para limpar, nem risco de trancar alguém do lado de fora com um dispositivo que nunca foi verificado.
A única chamada deste namespace que não precisa de sudo. Ela já está provando posse do dispositivo, que é justamente o que o sudo pediria.
unenroll
unenroll({ id, nonce }) → AuthMethod
Remove um fator. Devolve o que foi removido.
const { data: factors } = await nulvless.auth.factors.list();
const totp = factors?.find((factor) => factor.type === 'totp');
if (totp?.id) await nulvless.auth.factors.unenroll({ id: totp.id, nonce: code });idstringRequiredVindo do list().
noncestringOptionalNum ambiente que exige MFA, remover o último fator deixa a conta incapaz de completar uma entrada. Avise antes do último, ou combine a remoção com o cadastro de um substituto.
getRecoveryCodes
getRecoveryCodes({ nonce }) → { codes }
Devolve os códigos de recuperação da pessoa.
const { data } = await nulvless.auth.factors.getRecoveryCodes({ nonce: code });
// data.codes → string[]noncestringOptionalConfirmação de sudo.
Mostre uma vez, no cadastro, e faça a pessoa confirmar que guardou. Eles são o
único caminho de volta em autoatendimento para quem perde o dispositivo — a
alternativa é um caminho de suporte onde um admin remove o fator com
auth.admin.users.removeFactor, e a
plataforma não vai questionar essa chamada.
Um código de recuperação é enviado no campo code comum do
verifyChallenge — não há chamada separada
para resgatar um.
deleteRecoveryCodes
deleteRecoveryCodes({ nonce }) → null
Invalida o conjunto atual.
await nulvless.auth.factors.deleteRecoveryCodes({ nonce: code });noncestringOptionalÉ o que um botão de "gerar novos códigos" faz antes de emitir um conjunto novo. Sozinho, ele remove um plano de reserva em vez de acrescentar um, então raramente é a interação inteira.