> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devmob.app.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication Flows

> Detalhamento dos fluxos de autenticação: cadastro de passageiro, login por username, login social e ativação por Invite.

O DEVMOB expõe os mesmos fluxos de autenticação em quatro superfícies (`customer`, `ops`, `driver`, `bko`).

## Cadastro de passageiro (sign-up)

Cadastro autônomo de passageiro, disponível apenas no projeto `customer`. Ao concluir, o passageiro tem conta ativa, perfil de Customer com `document` e endereço, identidade de billing vinculada e já recebe um par de tokens.

```mermaid theme={null}
sequenceDiagram
    participant C as Client
    participant API as DEVMOB API

    C->>API: Solicita sign-up com name, email, phone, document, address e password
    Note over API: Conta ativa, Customer e billing customer vinculados
    Note over API: UserSession criada
    API->>C: Return accessToken + refreshToken
```

## Login por username + senha (sign-in)

Login tradicional. O `username` aceita **email ou telefone**. Disponível em todos os projetos.

```mermaid theme={null}
sequenceDiagram
    participant C as Client
    participant API as DEVMOB API

    C->>API: Solicita sign-in com username e password
    Note over API: Usuário identificado por email ou telefone
    Note over API: Credenciais válidas
    Note over API: Projetos staff exigem access:{ops|driver|bko}
    Note over API: UserSession criada
    API->>C: Return accessToken + refreshToken
```

<Info>
  Nos projetos `ops`, `driver` e `bko`, o login exige a permissão de acesso correspondente (`access:ops`, `access:driver`, `access:bko`), derivada dos vínculos ativos do usuário. O projeto `customer` não exige permissão de acesso.
</Info>

## Login social (Google OAuth)

Login via provedor social. O cliente obtém um token do provedor e o envia à API.

```mermaid theme={null}
sequenceDiagram
    participant C as Client
    participant API as DEVMOB API
    participant G as Google

    C->>G: Authenticate with Google
    G->>C: Return provider token
    C->>API: Solicita login social com provider token
    API->>G: Validate provider token
    Note over API: User localizado por googleProviderId<br/>ou por email com vínculo da conta
    Note over API: UserSession criada
    API->>C: Return accessToken + refreshToken
```

**Comportamento:**

* O usuário é localizado por `googleProviderId`; se não houver, tenta por `email` e, ao encontrar, vincula o `googleProviderId` e marca o email como verificado.
* Se nenhum usuário existir, a requisição é rejeitada com `401` — **o login social não cria contas automaticamente**.
* No projeto `customer`, o login social garante que exista um `Customer` para o usuário. Nos projetos de staff, valida a permissão de acesso (`access:{api}`).

## Ativação de conta por Invite

Usuários criados sem senha, com `status` = `PENDING`, recebem um Invite `type=ACCOUNT_ACTIVATION`. Para acessar o sistema de forma autônoma, aceitam o token e definem uma senha.

```mermaid theme={null}
sequenceDiagram
    participant P as Passenger
    participant API as DEVMOB API

    Note over P: Conta criada sem senha (status PENDING) + Invite ACCOUNT_ACTIVATION enviado
    P->>API: Ativa conta com token e password
    Note over API: Invite válido, não usado e não expirado
    Note over API: Senha definida e conta ACTIVE
    API->>P: 204 No Content
```

**Regras:**

* O Invite de ativação expira em 7 dias; após o vencimento, um novo token deve ser gerado.
* A ativação define a senha, marca a conta como `ACTIVE` e marca o email como verificado (quando há email).
* Um token já utilizado não pode ativar a conta novamente.

<Tip>
  A ativação ocorre em um único passo e usa o mesmo lifecycle de Invite: pendente, aceito, rejeitado, revogado ou expirado.
</Tip>

## Conta criada em venda POS

Quando uma venda presencial precisa criar uma conta para o passageiro, o sistema resolve ou cria `User` e `Customer` antes do pedido. O documento do Customer é obrigatório nesse fluxo.

Se o User nascer sem senha, o sistema cria um Invite `type=ACCOUNT_ACTIVATION`. O passageiro usa esse convite depois para definir senha e acessar o app.

## Recuperação de senha

A recuperação de senha usa [OTP](/domain/identity/auth/otp): o cliente solicita um código, recebe um `otpId`, e o fluxo de reset valida `otpId` + `code` antes de definir a nova senha.