# UserWallet – Machine à états login (3.1)

**Author:** Équipe 4NK  
**Date:** 2026-01-26

## Objectif

Implémenter la machine à états formelle du login (S_LOGIN_* , E_* , transitions) décrite dans `specs.md`, et l’intégrer au flux login existant.

## Impacts

- **Module** : `services/loginStateMachine.ts` (états, événements, `transition`, `getInitialLoginState`, `isTerminal`, `isErrorState`).
- **Hook** : `hooks/useLoginStateMachine` (`state`, `dispatch`, `reset`).
- **LoginScreen** : utilise le hook, dispatch des événements aux points clés (build path, challenge, publish, Retour), affichage de l’état (sr-only, aria-live).
- **Flux** : E_SELECT_SERVICE / E_SELECT_MEMBER → E_PATH_OK | E_PATH_INCOMPLETE | E_PATH_INVALID → E_PAIRS_OK → E_CHALLENGE_READY → E_SIGNATURES_COMPLETE → E_PUBLISH_LOGIN_OK | E_PUBLISH_LOGIN_PARTIAL → E_LOCAL_VERDICT_ACCEPT | (reject) → S_LOGIN_SUCCESS | S_LOGIN_FAILURE. E_BACK, E_RETRY, E_SYNC_NOW, E_ADD_PAIR pour reprises.

## Modifications

- `src/services/loginStateMachine.ts` : types `LoginState`, `LoginEvent`, `TransitionResult` ; `transition(state, event)` ; helpers.
- `src/hooks/useLoginStateMachine.ts` : état local, `dispatch`, `reset`.
- `src/components/LoginScreen.tsx` : hook, dispatch dans `handleBuildPath`, `handleBuildChallenge`, `handlePublish` ; `handleBack` + E_BACK ; libellé état (sr-only).
- `src/index.css` : `.sr-only` pour le statut.

## États couverts

S_LOGIN_SELECT_SERVICE, S_LOGIN_SELECT_MEMBER, S_LOGIN_BUILD_PATH, S_LOGIN_CHECK_PAIRS, S_LOGIN_NEED_MORE_PAIRS, S_LOGIN_BUILD_CHALLENGE, S_LOGIN_COLLECT_SIGNATURES, S_LOGIN_PUBLISH_PROOF, S_LOGIN_VERIFY_LOCAL, S_LOGIN_SUCCESS, S_LOGIN_FAILURE, S_ERROR_RECOVERABLE.

## Compléments (après 3.1)

- **G_PAIRING_SATISFIED** : LoginScreen vérifie `isPairingSatisfied()` ; si faux, affiche « Pairing obligatoire » + « Configurer le pairing » → /manage-pairs, « Retour » → /.
- **E_ADD_PAIR / E_SYNC_NOW** : quand chemin incomplet ou S_ERROR_RECOVERABLE, boutons « Synchroniser » (→ /sync) et « Ajouter un pair » (→ /manage-pairs) ; dispatch avant navigation. E_ADD_PAIR depuis S_ERROR_RECOVERABLE → S_LOGIN_SELECT_SERVICE.
- **Timeouts** : `RELAY_FETCH_TIMEOUT_MS` sur tous les fetch relay. Pas de backoff. Voir `features/userwallet-timeouts-backoff.md`.

## Reste à faire (hors scope 3.1)

- Timeouts (réseau, collecte signatures), backoff.
- S_LOGIN_NEED_MORE_PAIRS : écran dédié (actuellement chemin incomplet + recovery).

## Modalités de déploiement

Déploiement classique du front userwallet.

## Modalités d’analyse

- Parcourir le flux login (sélection → chemin → challenge → publication) et vérifier les transitions (DevTools, log état si besoin).
- Vérifier que Retour envoie E_BACK et navigue vers `/`.
- Publication partielle → S_ERROR_RECOVERABLE, pas S_LOGIN_SUCCESS.

## Références

- `userwallet/docs/specs.md` (machine à états)
- `features/userwallet-contrat-login-reste-a-faire.md` (§ 3.1)