MFA (double authentification)

Mailmus Auth supporte le TOTP (Google Authenticator, 1Password, Authy...) — pas de SMS, pour éviter la classe entière de vulnérabilités liées au SIM swapping.

Il y a deux flows distincts : l'inscription (l'utilisateur active le MFA sur son compte) et la vérification (le MFA est déjà activé, et se déclenche à chaque connexion).

Vérification — à chaque connexion

Toute méthode de première connexion (signIn, verifyOtp, verifyMagicLink, resetPassword, OAuth) renvoie un défi MFA au lieu de tokens directs si l'utilisateur a activé le MFA :

const result = await auth.signIn({ email, password });

if (isMfaChallenge(result)) {
  // { mfaRequired: true, challengeToken: string }
  const { endUser } = await auth.mfa.verify({ challengeToken: result.challengeToken, code: "123456" });
} else {
  console.log(result.endUser);
}

code accepte un code TOTP à 6 chiffres ou un code de secours à 10 caractères (consommé et invalidé après usage — chacun ne fonctionne qu'une fois).

Avec @mailmus/auth-react, <SignIn> gère cette étape automatiquement : le composant bascule vers un formulaire de vérification intégré dès que signIn() renvoie un défi, sans code supplémentaire de votre côté.

Inscription — activer le MFA

C'est un flow en 3 étapes, à faire une fois pendant que l'utilisateur est déjà connecté (aucun rapport avec le flow de vérification ci-dessus) :

// 1. Démarre l'inscription — génère un secret TOTP et un QR code.
const { secret, otpauthUrl } = await auth.mfa.enroll();

// 2. Affichez le QR code (encodez otpauthUrl, ex. avec la librairie `qrcode`)
//    et/ou le secret en saisie manuelle, puis récupérez le premier code
//    généré par l'app d'authentification de l'utilisateur.

// 3. Confirmez — le MFA n'est activé qu'à cette étape.
const { backupCodes } = await auth.mfa.confirm({ code: "123456" });
// backupCodes: string[10] — à afficher une seule fois, l'utilisateur doit les sauvegarder.

backupCodes n'est renvoyé qu'une seule fois, à la confirmation — Mailmus ne les stocke qu'en hash, impossible de les redemander plus tard. Prévoyez une UI qui force l'utilisateur à les copier/télécharger avant de continuer.

Désactiver le MFA

await auth.mfa.disable({ code: "123456" }); // TOTP ou code de secours

Avec @mailmus/auth-react

<MfaEnroll> couvre tout le flow d'inscription (QR code, secret manuel, confirmation, affichage des codes de secours avec bouton copier) :

<MfaEnroll onEnrolled={(backupCodes) => console.log(backupCodes)} />

<MfaDisable> couvre la désactivation :

<MfaDisable onDisabled={() => console.log("MFA désactivée")} />

Aucun composant équivalent n'existe ailleurs dans l'écosystème Mailmus (ni dans les pages hébergées, ni dans le panel admin) — c'est la seule UI d'inscription MFA prête à l'emploi.

Suivant

• OAuth — le MFA s'applique aussi aux connexions Google/GitHub/Apple.
• Référence API — endpoints mfa/*.