# Protocolo Shepherd 1 — Fluxo visual

Do início (verificação humana) ao fim (sessão ativa). Apenas o fluxo em diagrama.

---

## Fluxo completo: HV → Sessão

```mermaid
flowchart TB
    subgraph inicio [" "]
        A([Acesso à página de login])
    end

    subgraph hv ["Verificação humana (HV)"]
        B[initChallenge: token HV + script no cliente]
        C[Usuário preenche email, senha]
        D[Cliente envia hv_token + hv_js]
    end

    subgraph post ["POST /login"]
        E{CSRF válido?}
        F{HV válido?}
        G{Rate limit OK?}
        H{Email + senha válidos?}
        I{Usuário existe?}
        J{Senha OK?}
        K{Conta ativa?}
        L{Email verificado?}
    end

    subgraph decisao_2fa ["Decisão 2FA"]
        M{2FA ativo?}
        N{Redirect = qr-login-confirm?}
        O{Dispositivo confiável?}
        P[Redireciona login-2fa]
        Q[Envia código por email]
        R[Usuário digita código]
        S{Código válido?}
    end

    subgraph sessao ["Sessão"]
        T[Regenera session ID]
        U[Cria sessão: user, IP, user-agent]
        V[Trust device: marca ou rotação]
        W[SessionManager.createSession]
        X([Redirect: dashboard / destino])
    end

    subgraph qr ["Fluxo alternativo: Login por QR"]
        Y[Desktop: gera token QR]
        Z[Exibe QR]
        M1[Mobile: escaneia]
        M2{Mobile logado?}
        M3[Login com redirect qr-login-confirm<br/>sem 2FA]
        M4[qr-login-confirm: confirma]
        M5[Desktop: polling qr-login-status]
        M6[status = confirmed]
        M7[Cria sessão no desktop]
        M8([Redirect desktop])
    end

    A --> B --> C --> D
    D --> E
    E -->|Não| ER1[Erro: token inválido]
    E -->|Sim| F
    F -->|Não| ER2[Erro: falha HV]
    F -->|Sim| G
    G -->|Não| ER3[Erro: rate limit]
    G -->|Sim| H
    H -->|Não| ER4[Erro: campos]
    H -->|Sim| I
    I -->|Não| ER5[Erro: email não encontrado]
    I -->|Sim| J
    J -->|Não| ER6[Erro: senha incorreta]
    J -->|Sim| K
    K -->|Não| ER7[Erro: conta inativa]
    K -->|Sim| L
    L -->|Não| ER8[Erro: email não verificado]
    L -->|Sim| M

    M -->|Não| T
    M -->|Sim| N
    N -->|Sim| T
    N -->|Não| O
    O -->|Sim| V --> T
    O -->|Não| P --> Q --> R --> S
    S -->|Não| ER9[Erro: código inválido]
    S -->|Sim| T

    T --> U --> W --> X

    Y --> Z
    M1 --> M2
    M2 -->|Não| M3 --> M4
    M2 -->|Sim| M4
    M4 --> M5 --> M6 --> M7 --> M8
```

---

## Resumo dos nós

| Etapa        | Descrição breve                                                |
|-------------|-----------------------------------------------------------------|
| HV          | Desafio anti-bot no carregamento; validação no POST (token + JS). |
| CSRF        | Token de formulário validado antes de processar.               |
| Rate limit  | Bloqueio por excesso de tentativas (IP + janela).              |
| 2FA ativo?  | Se sim: redirect qr-login-confirm? → sim = sem 2FA. Dispositivo confiável? → sim = sem 2FA. Senão → login-2fa. |
| Sessão      | Regenera ID, grava user/IP/UA, opcional trust device, SessionManager, redirect. |
| QR          | Desktop gera QR; mobile escaneia e confirma (login sem 2FA se vier do redirect); desktop recebe sessão via polling. |