> ## 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.

# UserSession

> Sessão autenticada revogável com persistência server-side

`UserSession` representa uma sessão autenticada do usuário. Ela permite revogar acesso antes da expiração do `accessToken`, controlar refresh tokens e encerrar sessões automaticamente quando regras de segurança exigirem.

## Campos

| Campo                 | Tipo                  | Descrição                                                           |
| --------------------- | --------------------- | ------------------------------------------------------------------- |
| `userSessionId`       | `UUID`                | Identificador único da sessão. Também é usado como `sid` nos tokens |
| `userId`              | `UUID`                | Referência ao usuário autenticado                                   |
| `audience`            | `UserSessionAudience` | Superfície onde a sessão foi criada                                 |
| `refreshTokenHash`    | `String`              | Hash unidirecional do refresh token ativo da sessão                 |
| `deviceId`            | `String?`             | Identificador estável do dispositivo, quando informado pelo cliente |
| `deviceName`          | `String?`             | Nome exibível do dispositivo                                        |
| `userAgent`           | `String?`             | User agent capturado no login ou refresh                            |
| `ipAddress`           | `String?`             | IP capturado no login ou refresh                                    |
| `status`              | `UserSessionStatus`   | Estado manual da sessão. Default: `ACTIVE`                          |
| `lastUsedAt`          | `DateTime`            | Última vez em que a sessão foi usada em autenticação ou refresh     |
| `refreshExpiresAt`    | `DateTime`            | Data limite para uso do refresh token                               |
| `inactivityExpiresAt` | `DateTime?`           | Data limite por inatividade, quando a política estiver habilitada   |
| `revokedAt`           | `DateTime?`           | Data de revogação manual ou automática                              |
| `revokedBy`           | `UUID?`               | Usuário que revogou a sessão, quando a revogação for manual         |
| `revokedReason`       | `String?`             | Motivo técnico ou operacional da revogação                          |
| `createdBy`           | `UUID?`               | Usuário que criou a sessão, quando aplicável                        |
| `createdAt`           | `DateTime`            | Data de criação                                                     |
| `updatedBy`           | `UUID?`               | Usuário que fez a última atualização, quando aplicável              |
| `updatedAt`           | `DateTime`            | Data da última atualização                                          |

## Relacionamentos

* Relaciona-se com [User](/data-modelling/identity/user)

## Persistência

`UserSession` é persistida como estado server-side da autenticação. A aplicação precisa consultar a sessão pelo `sid` recebido no token e listar sessões por usuário para logout global e gestão de dispositivos.

| Acesso                        | Critério              | Uso                                                 |
| ----------------------------- | --------------------- | --------------------------------------------------- |
| Buscar sessão por token       | `userSessionId`       | Validar o `sid` em cada requisição autenticada      |
| Listar sessões do usuário     | `userId`              | Exibir dispositivos ativos e executar logout global |
| Filtrar sessões por audiência | `userId` + `audience` | Consultar sessões abertas por superfície            |

## Regras de Negócio

* O `accessToken` não é persistido. Ele carrega `sid`, `sub`, `aud`, `type`, `iat` e `exp`.
* A sessão não guarda `organizationId`, `membershipId`, roles ou permissions. Escopo e autorização são resolvidos pelo Profile e pelas regras do domínio de Authorization.
* O refresh token nunca é armazenado em texto puro nem com criptografia reversível. Apenas `refreshTokenHash` é persistido.
* A cada refresh bem-sucedido, um novo refresh token é emitido e `refreshTokenHash` é atualizado.
* `EXPIRED` não é status persistido. Expiração é calculada por `refreshExpiresAt` e `inactivityExpiresAt`.
* A sessão é inválida quando `status = REVOKED`, `refreshExpiresAt` passou ou `inactivityExpiresAt` passou.
* Alteração de senha, bloqueio de usuário, logout e logout global revogam sessões atualizando o estado da sessão por `sid`.
* A audiência da sessão precisa bater com o `aud` recebido no token.

## Enums

### UserSessionAudience

| Valor        | Descrição                                    |
| ------------ | -------------------------------------------- |
| `CUSTOMER`   | Sessão do app ou portal de passageiros       |
| `OPS`        | Sessão operacional de empresa ou cooperativa |
| `DRIVER`     | Sessão do app de motorista                   |
| `BACKOFFICE` | Sessão administrativa da plataforma          |

### UserSessionStatus

| Valor     | Descrição                                  |
| --------- | ------------------------------------------ |
| `ACTIVE`  | Sessão ativa e elegível para autenticação  |
| `REVOKED` | Sessão encerrada manual ou automaticamente |

## Example

```json theme={null}
{
  "userSessionId": "0197aa0b-5c2c-79fd-8f62-b5f9b3c5d5cb",
  "userId": "0197a7f5-2a88-7c1e-9b65-1f6d8f3b3a10",
  "audience": "OPS",
  "refreshTokenHash": "$protected_refresh_token_hash",
  "deviceId": "ios-3E4B9D",
  "deviceName": "iPhone 15 Pro",
  "userAgent": "DEVMOB Ops/1.8.0 iOS",
  "ipAddress": "203.0.113.10",
  "status": "ACTIVE",
  "lastUsedAt": "2026-07-04T14:25:00.000Z",
  "refreshExpiresAt": "2026-08-03T14:00:00.000Z",
  "inactivityExpiresAt": "2026-07-11T14:25:00.000Z",
  "revokedAt": null,
  "revokedBy": null,
  "revokedReason": null,
  "createdBy": "0197a7f5-2a88-7c1e-9b65-1f6d8f3b3a10",
  "createdAt": "2026-07-04T14:00:00.000Z",
  "updatedBy": "0197a7f5-2a88-7c1e-9b65-1f6d8f3b3a10",
  "updatedAt": "2026-07-04T14:25:00.000Z"
}
```