Nifram — Documentation équipe

Prompt de délégation — 2FA (désactivation, changement de méthode, escalade vendeur)

7 min de lecture

Rempli à partir du gabarit Template de prompt de delegation, selon la convention de classement décrite dans README - Convention de classement. Fichiers vault à joindre en pièce jointe avec ce prompt : voir tout en bas de ce document.

Contexte projet — Nifram

Tu travailles sur Nifram, une marketplace multi-acteurs pour le Bénin et la diaspora.

Stack :

  • Backend : Laravel 13.x (PHP 8.4+) — API REST versionnée /api/v1/, monolithe modulaire (app/Domains/<X>/, un domaine = une responsabilité)
  • Base de données : MySQL 8.x / MariaDB 10.6+ LTS
  • Frontend web : Next.js 16.2 (React 19, Server Components par défaut), shadcn/ui, Tailwind 4
  • Mobile : Expo (React Native)
  • Paiement : Moneroo (API HTTP directe, pas de SDK), idempotence obligatoire sur les webhooks
  • Auth : Sanctum (cookie httpOnly web, Bearer SecureStore mobile)

Acteurs : Client · Vendeur · Livreur · Agence de livraison · Ambassadeur · Admin · Super Admin

Règles non négociables :

  • Spécification avant code : ne jamais implémenter un module/écran sans sa spec écrite dans le vault (Modules/ ou Design/Specifications/)
  • Multidevise (XOF par défaut, USD/EUR en affichage) — jamais une devise codée en dur ; montants toujours en entier (centimes), jamais en flottant
  • Multilingue FR/EN — jamais un texte codé en dur côté frontend
  • Couche d’abstraction paiement déjà en place (Moneroo) — ne jamais coupler directement à un autre PSP sans passer par l’interface existante
  • Idempotence obligatoire sur les endpoints de paiement et les webhooks
  • API REST versionnée /api/v1/ — un breaking change devient /api/v2/, jamais une modification d’un endpoint existant
  • Documents KYC chiffrés au repos

Module/écran concerné : Module 01 — Authentification et comptes (volet 2FA)

Objectif

Permettre à toute personne de créer un compte unique et d’y accéder de façon sécurisée, et de protéger les accès sensibles par double authentification (2FA) — application TOTP en méthode privilégiée, avec code email et/ou SMS en secours, et codes de secours à usage unique.

Périmètre

Inclus dans ta tâche : activation/désactivation de la 2FA, changement de méthode active, et l’escalade progressive du 2FA pour les vendeurs (rappel → délai de grâce → blocage des actions commerciales). Exclus (traités dans d’autres tickets) : inscription/connexion de base, mot de passe oublié, intégration frontend des écrans.

Acteurs concernés

Tout utilisateur authentifié (activation/désactivation générale) ; Vendeur (escalade progressive spécifique) ; Admin/Super Admin et opérations de retrait (2FA obligatoire sans délai, déjà existant, non modifié par ce ticket).

Règles de gestion clés

  • RFC-026 : la 2FA vendeur est fortement recommandée dès l’entrée réelle dans la vie active de vendeur (date d’octroi du statut provisoire, ou complétion de l’Étape 3 de l’onboarding — Module 04 §“Étape 3”/§1bis). Rappels sur deux paliers configurables par l’admin (security.vendor_2fa_grace_days, défaut 45 jours ; puis security.vendor_2fa_grace_extra_days, défaut 7 jours). Passé les deux paliers sans 2FA configurée, les actions commerciales deviennent bloquées (catalogue, nouveaux produits, campagnes, retraits) — jamais la connexion, la messagerie ou les commandes en cours.
  • RFC-026 : champs shops.security_2fa_grace_started_at (immuable, point de départ du calcul de délai) et shops.security_2fa_last_reminder_stage (null / palier_1 / palier_2).
  • RFC-029 : désactivation de la 2FA possible à tout moment par tout utilisateur authentifié, après re-confirmation du mot de passe actuel dans le payload (empêche une session détournée de désactiver silencieusement). Aucune restriction supplémentaire liée au rôle sur cet endpoint — la protection réelle vient de la vérification à l’instant de l’action sensible, pas d’une interdiction de désactiver.
  • RFC-029 : la désactivation ne dispense jamais d’une exigence de 2FA déjà due (admin, retrait, vendeur post-délai de grâce) — vérifiée à l’instant de l’action sensible, jamais mise en cache depuis l’activation.
  • RFC-029 : changement de méthode active (ex. TOTP → email) exige lui aussi la re-confirmation du mot de passe (pas nécessaire pour la toute première activation) — la séquence technique exacte (désactivation puis réactivation, ou remplacement atomique) est un détail d’implémentation laissé libre.
  • RFC-029 — effet de bord vendeur : si un compte vendeur (shop) désactive sa 2FA avant l’échéance de son délai de grâce, réinitialiser shops.security_2fa_last_reminder_stage à null (le job de rappel réintègre ce compte dans le cycle normal — le point de départ security_2fa_grace_started_at reste immuable, pas de nouveau délai complet). S’il désactive après l’échéance, ne rien changer : le blocage s’applique déjà.
  • Standard TOTP / RFC 6238, aucun service tiers en runtime (bibliothèque locale). Codes email/SMS à usage unique avec expiration. Codes de secours à usage unique fournis à l’activation.

Dépendances

  • Module 01 lui-même (ticket #1 “Socle authentification” — doit être mergé en premier).
  • Module 04 (Boutiques et vendeurs) pour le point de départ du délai de grâce.
  • Module 15 (Administration et modération) pour les valeurs configurables des paliers.
  • Module 12 (Notifications multicanal) pour l’envoi des rappels (bannière + email).

Ta tâche

Implémenter le backend de la 2FA : activation (déjà existante, ne pas y toucher), désactivation, changement de méthode active, et le job planifié d’escalade du délai de grâce vendeur.

Ce qu’on attend comme livrable

Suivre l’ordre standard (Conception/Conventions Laravel Nifram.md §4) :

  1. Migration(s) — ajout des champs shops.security_2fa_grace_started_at et shops.security_2fa_last_reminder_stage si pas déjà présents (vérifier avec le ticket #1).
  2. Modèle Eloquent (méthodes/casts liés au 2FA sur User/Shop).
  3. Policy si nécessaire.
  4. Service de domaine (logique de désactivation, changement de méthode, calcul du palier de rappel).
  5. Form Request (validation payload — notamment le mot de passe actuel obligatoire).
  6. Contrôleur — endpoints :
    • POST /auth/2fa/disable (RFC-029, nouvel endpoint) — exige le mot de passe actuel, supprime two_factor_settings et les backup_codes associés, applique l’effet de bord vendeur ci-dessus.
    • Endpoint(s) pour le changement de méthode active (mécanisme technique libre, doit respecter la règle de re-confirmation du mot de passe).
    • POST /auth/login (vendeur) — réponse enrichie exposant palier_actuel (null/palier_1/palier_2) et jours_restants pour la bannière frontend (aucun nouvel endpoint, juste enrichir la réponse existante).
  7. Job planifié quotidien qui évalue le délai de grâce de chaque shop et fait progresser security_2fa_last_reminder_stage, déclenche les rappels (bannière + email via Module 12), et bloque les actions commerciales après le 2ᵉ palier.
  8. Tests Pest (Feature en priorité).

Contraintes spécifiques à cette tâche

  • Endpoint POST /auth/2fa/disable : nom de champ exact du payload à vérifier dans Conception/05 - Contrats API (REST v1).md (section D1) avant de coder — ne pas deviner un nom.
  • Ne pas confondre POST /auth/2fa/verify (confirme l’activation, utilisateur déjà authentifié) avec POST /auth/login/2fa-challenge (challenge pendant la connexion, utilisateur pas encore pleinement authentifié, payload login_challenge_token + code 2FA) — ce sont deux endpoints distincts, ne pas les fusionner ni réutiliser l’un pour l’autre.
  • Les valeurs des paliers (security.vendor_2fa_grace_days, security.vendor_2fa_grace_extra_days) sont configurables par l’admin — ne jamais les coder en dur, passer par la table settings générique (Module 00 backlog).

Ce que tu NE dois PAS faire

  • Ne pas toucher à POST /auth/2fa/enable ni POST /auth/2fa/verify (déjà existants, hors scope de ce ticket).
  • Ne pas implémenter le mot de passe oublié (ticket séparé, RFC-028).
  • Ne pas intégrer les écrans frontend (ticket séparé).
  • Ne pas bloquer la connexion, la messagerie ou les commandes en cours d’un vendeur en délai de grâce dépassé — seules les actions commerciales sont bloquées.

Format de réponse attendu

Plan d’implémentation d’abord (liste des fichiers à créer/modifier), puis le code complet de chaque fichier, dans l’ordre du cycle de réalisation ci-dessus.

Fichiers vault à joindre tels quels (pièce jointe, en plus de ce prompt)

  • Modules/Module 01 - Authentification et comptes.md
  • RFC/RFC-026 - Extension du 2FA obligatoire aux connexions vendeur.md
  • RFC/RFC-029 - Desactivation de la 2FA et changement de methode.md
  • Conception/05 - Contrats API (REST v1).md (au moins la section D1 — Identité & Accès)
  • Conception/06 - Workflows detailles et machines a etats.md (machine à états A15)
  • Conception/Matrice des permissions (RBAC).md (lignes “Activer 2FA” / “Désactiver 2FA”)

Liens

Vue Graphique