> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Coleção Tokens

`tokens` contém tokens de uso único: o segredo num link que permite a alguém definir uma palavra-passe. Um documento é um token. Não há modelo Mongoose; o web escreve a coleção através de `services/web/app/src/Features/Security/OneTimeTokenHandler.mjs` com o driver nativo.

#### Campos

| Campo | Tipo | Significado | Origem |
| - | - | - | - |
| `_id` | ObjectId | Id do documento. | `OneTimeTokenHandler.mjs:40` |
| `use` | String | Para que serve o token, veja [Utilizações](#uses) abaixo. Todas as pesquisas filtram por ele. | `OneTimeTokenHandler.mjs:41` |
| `token` | String | O segredo no link: 32 bytes aleatórios como 64 caracteres hexadecimais, guardado tal como está. | `OneTimeTokenHandler.mjs:38,42` |
| `data` | Object | O que o token representa, devolvido quando é usado. | `OneTimeTokenHandler.mjs:43` |
| `data.user_id` | String | Id do utilizador, escrito como string por todos os chamadores. | `services/web/app/src/Features/PasswordReset/PasswordResetHandler.mjs:27`, `services/web/app/src/Features/User/UserRegistrationHandler.mjs:117`, `services/web/modules/admin-tools/app/src/AdminUserManager.mjs:79` |
| `data.email` | String | Email do utilizador quando o token foi criado. Uma reposição de palavra-passe procura o utilizador por este email principal (`PasswordResetHandler.mjs:66-70`). | igual a `data.user_id` |
| `createdAt` | Date | Momento da criação. O índice TTL apaga o token 90 dias depois. | `OneTimeTokenHandler.mjs:36,44` |
| `expiresAt` | Date | `createdAt` mais `expiresIn` segundos: 1 hora por omissão, 1 semana para um link de ativação. As pesquisas ignoram o token depois deste momento. | `OneTimeTokenHandler.mjs:35-37,45` |
| `peekCount` | Number | Quantas vezes o token foi consultado sem ser usado. Cada `peekValueFromToken` soma 1; ao chegar a 4 (`MAX_PEEKS`), o token deixa de funcionar. | `OneTimeTokenHandler.mjs:8-31,107` |
| `usedAt` | Date | Momento em que o token foi usado ou cancelado. As pesquisas ignoram um token que o tenha. | `OneTimeTokenHandler.mjs:51-104` |

#### Utilizações

| `use` | Funcionalidade | Expiração | Código |
| - | - | - | - |
| `password` | Email de reposição da palavra-passe, a partir da página "esqueci-me da palavra-passe" | 1 hora | `PasswordResetHandler.mjs:14-42` |
| `password` | Link de ativação: uma conta criada com uma palavra-passe aleatória e depois um link para definir uma. Usado pelo registo público (`services/web/modules/login-register/app/src/RegisterController.mjs:65`), pela página de registo de administração de `user-activate` (`services/web/modules/user-activate/app/src/UserActivateController.mjs:27-30`) e pelo script `create-user` (`services/web/modules/server-ce-scripts/scripts/create-user.mjs:21`) | 1 semana | `UserRegistrationHandler.mjs:97-130` |
| `password` | Link de ativação ou de reposição da palavra-passe enviado a partir do painel de administração (módulo `admin-tools`) | 1 semana (ativação), 1 hora (reposição) | `AdminUserManager.mjs:76-103,196-206` |
| `email_confirmation` | Link de confirmação de email. Apenas lido: já nada neste repositório cria estes tokens, porque a confirmação agora envia um código de 6 dígitos (`services/web/app/src/Features/User/UserEmailsConfirmationHandler.mjs:15-35`) | | `UserEmailsConfirmationHandler.mjs:12,37-66` |

#### Quem escreve

| Código | O que faz |
| - | - |
| `OneTimeTokenHandler.mjs:34-49` (`getNewToken`) | Insere um token. Chamadores: `PasswordResetHandler.mjs:28`, `UserRegistrationHandler.mjs:115-119`, `AdminUserManager.mjs:77-81`. |
| `OneTimeTokenHandler.mjs:8-32` (`peekValueFromToken`) | Devolve `data` de um token válido e soma 1 a `peekCount`. Usado quando a página de reposição da palavra-passe abre (`services/web/app/src/Features/PasswordReset/PasswordResetController.mjs:195-208`), novamente quando a nova palavra-passe é definida (`PasswordResetHandler.mjs:94-96`), e pela confirmação de email (`UserEmailsConfirmationHandler.mjs:38-41`). |
| `OneTimeTokenHandler.mjs:75-88` (`expireToken`) | Define `usedAt` num token: depois de definida uma nova palavra-passe (`PasswordResetHandler.mjs:44-48,119`) ou confirmado um email (`UserEmailsConfirmationHandler.mjs:65`). |
| `OneTimeTokenHandler.mjs:90-104` (`expireAllTokensForUser`) | Define `usedAt` em todos os tokens `password` abertos de um utilizador, quando o utilizador muda a palavra-passe nas definições (`services/web/app/src/Features/User/UserController.mjs:146-149`) ou um administrador a define no painel de administração (`AdminUserManager.mjs:479-488`). |

#### Quem lê

| Código | O que faz |
| - | - |
| `PasswordResetHandler.mjs:50-70,94-119` | Converte um token de reposição ou de ativação no utilizador e depois define a palavra-passe. A página de ativação de `user-activate` apenas passa o token a este formulário. |
| `UserEmailsConfirmationHandler.mjs:37-66` | Confirma um email a partir de um token `email_confirmation` do utilizador com sessão iniciada. |
| `AdminUserManager.mjs:213-223` (module `admin-tools`) | Encontra o token de ativação aberto de um utilizador, para voltar a mostrar o link de ativação no painel de administração. Lê `db.tokens` diretamente. |

#### Índices

| Nome | Chaves | Opções | Migração |
| - | - | - | - |
| `token_1_use_1` | `{ token: 1, use: 1 }` | único | `20190912145031_create_tokens_indexes.mjs` |
| `createdAt_1` | `{ createdAt: 1 }` | TTL, `expireAfterSeconds: 7776000` (90 dias) | `20210407085118_token-expiry-with-ttl-index.mjs` |
| `data.user_id_1` | `{ "data.user_id": 1 }` | | `20231113173237_tokens_user_id_index.mjs` |

As migrações estão em `tools/migrations/`.

#### Notas

* Um token usado ou expirado não é apagado de imediato: fica, com `usedAt` ou um `expiresAt` passado, até o índice TTL o remover 90 dias após `createdAt`.
* `OneTimeTokenHandler` também tem `getValueFromTokenAndExpire` (`OneTimeTokenHandler.mjs:51-73`), mas nada o chama.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.