funifier-mcp 0.2.25 → 0.2.27

package/datasource-funifier-docs/knowledge/modules/auth.md

@@ -1,104 +1,753 @@
-# Auth (Autenticação)
+# `auth`
 
-**Acesso Studio:** `/studio/auth`
+**Acesso Studio:** `/studio/security` _(rota de frontend — não verificável neste repositório)_
 **API Endpoint:** `/v3/auth`
+**Coleções MongoDB:** `auth_module` (gerenciada por este endpoint), `authentication` (legada v1/v2). Lê — sem gravar — `security` e `principal`.
 
-## O que é
+> Documentação de engenharia reversa do módulo `auth` do projeto `funifier-service`. Baseada exclusivamente no comportamento real do código-fonte (pacotes `com.funifier.engine.auth.*`, `com.funifier.rest.v3.*`). Cada comportamento não óbvio cita `arquivo:linha`.
 
-Gerenciamento de autenticação e critérios básicos de segurança. Permite configurar como será o processo de login dos jogadores, definindo exigência de senha, auto-criação de usuários, geração de tokens de acesso (incluindo tempo de expiração e revalidação). Também permite criar rotinas personalizadas de autenticação (Auth Module) para SSO, validação externa e logs de login.
+---
 
-## Quando usar
+## 1. Visão Geral
 
-- Para configurar login de jogadores
-- Para gerar tokens de acesso
-- Para implementar SSO com sistemas corporativos
-- Para criar validações customizadas de autenticação
+O módulo `auth` tem duas responsabilidades distintas, ambas servidas pela classe `AuthenticationRest` (`@Path("v3/auth")`, `rest/v3/rest/AuthenticationRest.java:52`):
 
-## Checklist de Configuração no Studio
+1. **Emissão de tokens** (`POST /v3/auth/token`): implementação parcial de OAuth 2.0 (RFC6749) que autentica jogadores/aplicações e emite JWTs Bearer. Suporta `client_credentials`, `password` e `refresh_token`.
+2. **CRUD de Auth Modules** (`/v3/auth/module`): cadastro de scripts Groovy customizados que rodam no login do jogador (PAM stacking — login por CPF, SSO externo, senha mestre, etc.).
 
-- [ ] Definir se senha é obrigatória
-- [ ] Configurar auto-criação de usuários
-- [ ] Definir tempo de expiração do token
-- [ ] Configurar módulo de autenticação customizado (se necessário)
+A **autorização** de todas as requisições `/v3/*` acontece no `SecurityFilter` (`rest/v3/filter/SecurityFilter.java:27`), um servlet filter que valida o token e o escopo antes de liberar o acesso. O `SecurityFilter` é descrito aqui porque é o consumidor em runtime dos tokens emitidos pelo `/v3/auth/token`.
 
-## API Endpoints
+A lógica de autenticação de jogador vive em `com.funifier.engine.auth.AuthenticationManager` (`engine/auth/AuthenticationManager.java:37`), instanciada por gamificação via `FrontController.getInstance(apiKey).getManagerFactory()`.
 
-### Autenticar Jogador
-**Método:** POST
-**Endpoint:** `/v3/auth/token`
+> **Escopo deste documento:** cobre exclusivamente a autenticação de **jogadores** (`/v3/auth`). Subsistemas correlatos — `/v3/system/auth/module` (auth modules de usuário Studio), `/v3/sso/saml/*` (SSO de administradores Studio) e 2FA (usuários de conta) — são explicitamente delimitados na seção 7.
+
+---
+
+## 2. Arquitetura e Fluxos
+
+### 2.1 Pipeline principal — `POST /v3/auth/token`
+
+O mesmo path aceita dois `Content-Type` em métodos diferentes:
+
+- `application/x-www-form-urlencoded` → `AuthenticationRest.token()` (`:88`)
+- `application/json` → `AuthenticationRest.tokenJson()` (`:232`)
+
+Os dois métodos **não são equivalentes** (ver 2.4). Sequência do `token()` (form):
+
+```
+POST /v3/auth/token
+  1. [Roteamento por grant_type] → request.getParameter("grant_type")        token():98
+  2a. client_credentials:
+       isAppSecretAllowed(client_secret)        AuthenticationManager:189
+       se inválido → 401 UNAUTHORIZED_CLIENT     token():108
+       findApplication(secret) → app.scope, app.whitelist   token():111-112
+       accessToken(scale=DAY, amount=7) + refreshToken (1 ano)   token():112-113
+  2b. password:
+       authenticateModules(req, m, context)      token():133 → AuthenticationManager:693
+       moduleStatus==2 → 401 auth_module_failed (se houver output) ou 400 invalid_grant   token():135-144
+       username = req.getParameter("username")   ← pode ter sido reescrito por módulo   token():148
+       moduleStatus==1  OU  (moduleStatus==0 && authenticatePassword(player,password))    token():150
+       findRoleCalculatedToPlayer(player) → scope, expiration, whitelist    token():151-155
+       accessToken(scope, expiration, role.whitelist) + refreshToken    token():155-156
+  2c. refresh_token:
+       accessTokenWithRefreshToken(refresh_token)   token():171 → TokenUtil:80
+       gera novo refresh_token (rotativo)   token():181
+  2d. qualquer outro grant_type → 400 invalid_grant   token():187
+```
+
+**Algoritmo de decisão dos Auth Modules** (`AuthenticationManager.authenticateModules`, `:693`):
+
+```
+status = 0; ok_sufficient = 0; ok_required = 0; tot_required = 0
+para cada AuthModule ordenado por "order" asc (findAll():685):
+    se relevance == "required": tot_required++
+    se limite diário de execução de auth (newTriggerExecution) excedido:
+        loga e PULA o módulo (não falha)               :763-765
+    senão:
+        result = AuthRunner.run(module, ...)            :729
+        se result.userid == null E relevance == "requisite":
+            return status = 2   (falha imediata)        :733-736
+        se result.userid != null:
+            se required  → ok_required++
+            se sufficient → ok_sufficient++             :739-746
+    se o módulo lançar exceção: e.printStackTrace() e CONTINUA  :767-770
+fim-para
+se ok_sufficient > 0:                 status = 1        :774
+senão se tot_required != ok_required: status = 2        :778
+senão:                                status = 0
+```
+
+- `status=0` → não houve `sufficient`; segue para `authenticatePassword` (auth Funifier padrão).
+- `status=1` → ao menos um `sufficient` retornou userid; **pula** a validação de senha Funifier.
+- `status=2` → falha; o token **não** é emitido.
+
+### 2.2 Fluxo de emissão de token (visão geral)
+
+### Fluxo — POST /v3/auth/token (form-urlencoded)
+
+```mermaid
+flowchart TD
+    A[POST /v3/auth/token] --> B{grant_type?}
+    B -->|client_credentials| C[isAppSecretAllowed]
+    B -->|password| D[authenticateModules - PAM]
+    B -->|refresh_token| E[accessTokenWithRefreshToken]
+    B -->|outro| X[400 invalid_grant]
+
+    C -->|false| Y[401 unauthorized_client]
+    C -->|true| F[findApplication: scope + whitelist]
+    F --> T[accessToken DAY,7 + refreshToken 1 ano]
+
+    D --> G{moduleStatus}
+    G -->|2 + output| Z[401 auth_module_failed]
+    G -->|2| X
+    G -->|1| H[findRoleCalculatedToPlayer]
+    G -->|0| I[authenticatePassword]
+    I -->|lança AuthenticationException| X
+    I -->|true| H
+    H --> T2[accessToken scope/expiration/whitelist + refreshToken]
+
+    E --> T3[novo access_token + novo refresh_token]
+    T --> OK[200 Bearer]
+    T2 --> OK
+    T3 --> OK
+```
+
+### 2.3 PAM Stacking — execução dos Auth Modules
+
+### Sequência — authenticateModules
+
+```mermaid
+sequenceDiagram
+    participant R as AuthenticationRest.token
+    participant M as AuthenticationManager
+    participant Run as AuthRunner
+    participant G as Script Groovy
+
+    R->>M: authenticateModules(req, manager, context)
+    loop cada AuthModule (order asc)
+        M->>Run: run(module, req, manager, context)
+        Run->>Run: compila/recupera classe do cache
+        Run->>G: invokeMethod("authenticate", req)
+        G-->>Run: userid (String) ou null
+        Run-->>M: {userid, err, out, millis}
+        alt requisite e userid == null
+            M-->>R: status = 2 (falha imediata)
+        else sufficient e userid != null
+            M->>M: ok_sufficient++
+        else required e userid != null
+            M->>M: ok_required++
+        end
+    end
+    M-->>R: AuthModulesResult(status 0/1/2)
+```
+
+### 2.4 Diferenças entre `token()` (form) e `tokenJson()` (JSON)
+
+`tokenJson()` (`:232`) é uma reimplementação **mais fraca** do que `token()`. Diferenças confirmadas no código:
+
+| Aspecto | `token()` form (`:88`) | `tokenJson()` JSON (`:232`) |
+|---|---|---|
+| `grant_type=refresh_token` | Suportado (`:167`) | **Não implementado** (cai no `else` → 400, `:311`) |
+| Emite `refresh_token` | Sim (`:113`, `:156`) | **Não** — nenhuma resposta inclui refresh_token |
+| Claim `whitelist` no token | Sim, propaga `app.whitelist`/`role.whitelist` (`:112`, `:155`) | **Não** — chama `accessToken(...)` sem whitelist (`:262`, `:300`) |
+| Chave do apiKey | `apiKey` | `client_id` (cc) / `apiKey` (password) |
+
+**Consequência de segurança:** tokens emitidos pelo endpoint JSON **não carregam a claim `whitelist`**. Como o `SecurityFilter` só valida whitelist quando a claim existe (`SecurityFilter:189`), tokens minteados via JSON **ignoram silenciosamente** a restrição de IP/domínio configurada na Application/Role.
+
+### 2.5 Pipeline — `SecurityFilter` (autorização de toda requisição `/v3/*`)
+
+```
+doFilter():
+  1. método OPTIONS → passa direto (preflight CORS)          SecurityFilter:75
+  2. apikey = AuthBean.getApiKey(Authorization)              :81
+  3. entity   = path sem "/v3/" (primeiro segmento)          :84-88
+     entity_full = path sem "/v3/" com "/" → "_"
+  4. rate limit: StatisticManager.newApiRequest(method, entity)  :98
+        se estourou → 401 "You have exceeded your gamification daily api requests limits"  :100
+  5. paths públicos (lista hardcoded) → passa direto         :107-150
+  6. detecção do tipo de auth via header (usa .contains()):  :152-187
+        Basic   → authPublic / authBasic / findApplication → scope + whitelist
+        Account → AccountManager.isAppSecretAllowed (NÃO define scope)
+        Studio  → TokenUtil.getValueStudio (NÃO define scope)
+        Bearer  → TokenUtil.getValue(...,"apiKey"|"account"); scope + whitelist do token
+  7. se whitelist != null → isRequestWhiteListed(referer/origin/ip)  :189-197
+  8. se scope != null → verificação de escopo vs método/entity     :200-265
+  9. erro → 401 com mensagem específica; senão → filter.doFilter()  :267-292
+```
+
+**Mapeamento método→ação de escopo** (`SecurityFilter:205`): `GET→read`, `POST→write`, `PUT→write`, **demais → método em minúsculas** (logo `DELETE→delete`). A liberação ocorre se o escopo contém `{m}_all`, ou a lista contém `{m}_{entity_full}`, ou `{m}_{full_menos_1}_all`, ou `{m}_{full_menos_2}_all` (`:209-235`).
+
+---
+
+## 3. Estrutura dos Objetos
+
+### 3.1 `AuthModule` — módulo customizado (coleção: `auth_module`)
+
+Mapeado em `engine/auth/AuthModule.java`. Coleção definida em `Entity.AUTH_MODULE` → `"auth_module"` (`util/Entity.java:253`).
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|---|---|---|---|---|
+| `_id` | String | `Guid.newShortGuid()` se ausente | não | Id; gerado no `add()` se nulo/vazio (`AuthenticationManager:659`) |
+| `name` | String | null | não | Nome descritivo |
+| `script` | String | — | sim | Código Groovy com método `authenticate(request)` |
+| `relevance` | String | null | sim | `required`, `requisite`, `sufficient`, `optional` |
+| `order` | int | `0` | não | Ordem de execução ASC (`findAll().sort("{order:1}")`, `:687`) |
+| `created` | Date | `new Date()` na 1ª gravação | não | Definido apenas se nulo (`:660`) |
+| `updated` | Date | `new Date()` a cada `add()` | não | Sempre sobrescrito no save (`:663`) |
+| `timeout` | Long | `5` (segundos) | não | Timeout do `future.get` (`AuthRunner:229-232`) — ver 6.3 |
+
+**Constantes de `relevance`** (`AuthModule.java:12-15`) e comportamento PAM real (`authenticateModules`):
+
+| Valor | Comportamento confirmado no código |
+|---|---|
+| `requisite` | Se `userid == null` → falha **imediata** (`status=2`, return) (`:733`). Se sucesso, **não** é contabilizado em `ok_required`/`ok_sufficient`. |
+| `sufficient` | Se `userid != null` → `ok_sufficient++`; ao final, qualquer `ok_sufficient>0` ⇒ `status=1` (pula senha Funifier) (`:743`,`:774`). |
+| `required` | Conta em `tot_required`; sucesso ⇒ `ok_required++`. Se ao final `tot_required != ok_required` (e sem sufficient) ⇒ `status=2` (`:720`,`:740`,`:778`). |
+| `optional` | **Resultado totalmente ignorado** — não há ramo para `optional` em `authenticateModules`. |
+
+> **Comportamento silencioso:** um módulo `requisite` que **lança exceção** (em vez de retornar `null`) é capturado por `catch(Exception)` com apenas `printStackTrace()` (`:767-770`) e o loop **continua** — não dispara `status=2`. Só o retorno `null` de um `requisite` causa falha imediata.
+
+### 3.2 `Authentication` — sessão legada (coleção: `authentication`)
+
+Mapeado em `engine/auth/Authentication.java`. **Não é usado pelo `/v3/auth/token`** — o JWT v3 é stateless. Esta coleção só é lida/gravada pelos métodos legados v1/v2 (`authenticate(playerId)`, `logout`, `isAuthenticated`).
+
+| Campo | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `_id` (`access_token`) | String | `Guid.newShortGuid()` | Token de sessão legado |
+| `api_key` | String | null | API key da gamificação |
+| `auth_mode` | String | null | IMPLICIT, PASSWORD, CREDENTIAL, FACEBOOK, GOOGLE |
+| `player` | String | — | Id do jogador |
+| `expires_in` | Date | null | Expiração da sessão |
+| `language` | String | "en-US" | Idioma |
+| `host` | String | null | Host de origem |
+| `developer` | boolean | false | Permissão de edição inline |
+
+**Campos removidos/legados (comentados no código, `Authentication.java:18-20`):** `ip_adress` (typo no original), `session`, `userId`.
+
+### 3.3 `Security` — configuração da gamificação (coleção: `security`)
+
+Mapeado em `engine/security/Security.java`. **Documento único por gamificação** — `SecurityDaoMongo.update()` faz `c.remove()` (todos) e depois `save()` (`SecurityDaoMongo.java:11`). Gerenciado pelo endpoint `/v3/security`, **não** por `/v3/auth`. O `auth` apenas **lê** este documento.
+
+| Campo | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `_id` | String | — | Id |
+| `created_at` / `updated_at` | Date | null | Timestamps |
+| `requirePassword` | boolean | `false` | Se `false`, BCrypt **não** é exigido (ver 5.1) |
+| `createPlayerIfDontExist` | boolean | **`true`** | Auto-cria jogador no 1º login (`Security.java:18`) |
+| `timeZone` | String | null | Fuso da gamificação |
+| `inlineEditable` | boolean | false | Edição inline no Studio |
+| `appIdFacebook` / `appSecretFacebook` | String | null | Credenciais Facebook (só fluxo legado) |
+| `appIdGoogle` / `appSecretGoogle` | String | null | Credenciais Google (só fluxo legado) |
+| `appIdTwitter` / `appSecretTwitter` | String | null | Campos presentes, **sem implementação** |
+| `apps` | List\<Application\> | `[]` | Aplicações (app_secret + scope) |
+| `roles` | List\<Role\> | `[]` | Roles (timeout + scope) |
+| `websites` | List\<String\> | `[]` | Whitelist de domínios (modo IMPLICIT legado) |
+| `runInSilentMode` | boolean | false | Modo silencioso |
+| `baselines` | List\<BaseLine\> | `[]` | Configurações baseline |
+| `homepage` | String | null | Página inicial no Studio |
+| `ldap` | LDAPConfig | null | Config LDAP (implementação comentada — ver 7) |
+
+> **Default ausente = ainda autentica.** `SecurityDaoMongo.find()` retorna `new Security()` quando **não existe** documento (`SecurityDaoMongo.java:18`). Como o construtor default deixa `createPlayerIfDontExist=true` e `requirePassword=false`, uma gamificação sem documento `security` **autentica qualquer jogador sem senha e o cria**.
+
+### 3.4 `Application` — app registrado (embutido em `security.apps`)
+
+`engine/security/Application.java`.
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `name` | String | Nome descritivo |
+| `app_secret` | String | Secret para Basic/`client_credentials` |
+| `scope` | String | Escopos separados por vírgula |
+| `whitelist` | List\<String\> | IPs/domínios autorizados |
+
+**Constantes de escopo (`Application.java:7-19`)** — valores literais usados pelo `SecurityFilter`:
+
+| Constante | Valor | Significado |
+|---|---|---|
+| `SCOPE_READ_ALL` | `read_all` | Ler qualquer entidade |
+| `SCOPE_WRITE_ALL` | `write_all` | Escrever qualquer entidade |
+| `SCOPE_DELETE_ALL` | `delete_all` | Deletar qualquer entidade |
+| `SCOPE_DATABASE` | `database` | Acesso ao endpoint `/v3/database` |
+| `SCOPE_WRITE_ACTIONLOG` | `write_actionlog` | Escrever em `/v3/action/log` (tratamento especial, `SecurityFilter:238`) |
+| `SCOPE_WRITE_UPLOAD` | `write_upload` | Upload de arquivos |
+| `SCOPE_READ_CRYPTED` | `read_encrypted_field_values` | Ler campos criptografados |
+| `SCOPE_READ_PLAYER_PASSWORD` | `read_encrypted_player_password` | Ler senha do player |
+| `SCOPE_CROSSDOMAIN` | `cross_domain` | Excluir gamifications/accounts de outras contas |
+
+### 3.5 `Role` — role de jogador (embutido em `security.roles`)
+
+`engine/security/Role.java`. **Diferente** de `com.funifier.engine.system.role.Role` (roles de usuário Studio).
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `name` | String | Identificador (ex.: `player`, `public`) |
+| `timeout` | String | Ex.: `7d`, `1h`, `30m` — interpretado por `DateUtil.fromKeyword("+"+timeout)` |
+| `scope` | String | Escopos separados por vírgula |
+| `whitelist` | List\<String\> | IPs/domínios autorizados |
+
+### 3.6 `Principal` — vínculo player↔roles (coleção: `principal`)
+
+`engine/player/Principal.java`. Lido por `findRoleCalculatedToPlayer` para descobrir as roles do jogador.
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `_id` | String | Id do principal |
+| `name` | String | Nome |
+| `type` | Integer | `0`=USER, `1`=TEAM (`TYPE_USER`/`TYPE_TEAM`) |
+| `teamId` / `userId` | String | Referência conforme o tipo |
+| `roles` | List\<String\> | Nomes das roles do jogador |
+
+> **Importante:** jogadores criados pelo `/v3/auth/token` (password) **não recebem Principal** (ver 5.2). Logo `principal` é `null` para eles e o cálculo de role cai no ramo "sem principal".
+
+### 3.7 JWT — estrutura interna dos tokens
+
+Gerados em `TokenUtil` com `io.jsonwebtoken` (jjwt), assinatura **HS512**, payload comprimido com **GZIP** (`TokenUtil.java:30-39`).
+
+**access_token** (claims, `:30`,`:37`,`:137`,`:143`):
+
+| Claim | Presente quando |
+|---|---|
+| `apiKey` | Sempre (gamificação) |
+| `appSecret` | Apenas `client_credentials` |
+| `player` | Apenas `password` |
+| `scope` | Sempre |
+| `account` / `user` | Tokens de conta / usuário Studio |
+| `whitelist` | Apenas quando emitido pelo endpoint **form** com whitelist configurada |
+
+**refresh_token** (`generateRefreshToken`, `:45`): claims **ofuscados** `apk`, `aps`, `pla`, `acc`, `usr`; validade **1 ano** (`TimeScale.YEAR, 1`); **sem escopo** ("este token nao tem acesso a nada").
+
+---
+
+## 4. Endpoints
+
+### `POST /v3/auth/token`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Emitir access_token OAuth 2.0 |
+| Autenticação | Nenhuma — path público (`SecurityFilter:112`) |
+| Content-Type | `application/x-www-form-urlencoded` **ou** `application/json` (lógicas distintas — ver 2.4) |
+
+`expires_in` na resposta é o **timestamp Unix em milissegundos** da expiração (`Long.toString(expiration.getTime())`), **não** segundos como o padrão OAuth2.
+
+#### grant_type=client_credentials
+
+| Param | Descrição |
+|---|---|
+| `client_id` | API key da gamificação |
+| `client_secret` | App secret cadastrado em `security.apps` |
+| `grant_type` | `client_credentials` |
+
+**Comportamento real:** valida o secret (`isAppSecretAllowed`); usa `app.scope`; token válido por **7 dias fixos** (`TimeScale.DAY, 7`, `:112`). No endpoint **form**, emite `refresh_token` e propaga `app.whitelist`; no **JSON**, não emite refresh_token nem whitelist (`:262`). Secret inválido → **HTTP 401** (`unauthorized_client`).
 
-**Exemplo de Body:**
 ```json
-{
-  "apiKey": "YOUR_API_KEY",
-  "grant_type": "password",
-  "username": "tom",
-  "password": "123"
-}
+// Request (JSON)
+{ "grant_type": "client_credentials", "client_id": "5a3f...567", "client_secret": "abc123xyz" }
+// Response
+{ "access_token": "eyJ...", "expires_in": "1748387200000", "token_type": "Bearer" }
+```
+
+#### grant_type=password
+
+| Param | Descrição |
+|---|---|
+| `apiKey` | API key da gamificação |
+| `username` | Id do jogador (pode ser reescrito por Auth Module — `:148`) |
+| `password` | Senha (exigida só se `requirePassword=true` **e** enviada — ver 5.1) |
+| `grant_type` | `password` |
+
+**Comportamento real:**
+1. Roda os Auth Modules (PAM). `status=2` ⇒ 401 `auth_module_failed` (com `output`) ou 400 `invalid_grant`.
+2. Um Auth Module pode **substituir o `username`** via `request.setParameter("username", novo)` (`AuthRequest:65`); o valor reescrito é relido em `:148`.
+3. `status=1` (sufficient) pula a validação de senha; `status=0` chama `authenticatePassword`.
+4. Escopo/expiração derivam de `findRoleCalculatedToPlayer`; default quando não há role/scope: `read_all,write_actionlog,write_upload` e `+7d` (`:152-153`).
+5. Form emite `refresh_token` (1 ano); JSON não.
+
+```json
+// Request (JSON)
+{ "grant_type": "password", "apiKey": "5a3f...567", "username": "tom", "password": "abc123" }
 ```
 
-**Exemplo de Resposta:**
+#### grant_type=refresh_token
+
+> Disponível **apenas** via form-urlencoded. O `tokenJson` não implementa este branch (cai em 400, `:311`).
+
+| Param | Descrição |
+|---|---|
+| `refresh_token` | Refresh token previamente emitido |
+| `grant_type` | `refresh_token` |
+
+**Comportamento:** decodifica os claims ofuscados, reconstrói o access_token com as mesmas credenciais (`TokenUtil.generateAccessTokenWithRefreshToken:80`) e emite um **novo** refresh_token rotativo (`:181`). Só reconstrói para `apiKey` (app ou player); refresh de `account`/`user` retorna `null` ⇒ 401.
+
+---
+
+### `GET /v3/auth/module`
+
+| Aspecto | Detalhe |
+|---|---|
+| Autenticação | Bearer (escopo via SecurityFilter) |
+
+**Query params** (`findAuthModules:352` → `AuthenticationManager.findAll:791`):
+
+| Param | Descrição |
+|---|---|
+| `id` | Filtro por `_id` exato |
+| `q` | **Query Mongo inline injetada crua** na pipeline `$match` (`:809`) — ver 8 |
+| `published_min` / `published_max` | Faixa de `created` (RFC3339 ou keyword `-1d`) |
+| `orderby` | Campo de ordenação |
+| `reverse` | `true` = desc |
+| `max_results` | Limite (default **100** se ≤ 0, `:804`) |
+
+A consulta é uma agregação MongoDB com `$match`, `$sort` e `$limit`.
+
+### `GET /v3/auth/module/{id}`
+Retorna um `AuthModule` por id (`find:324` → `:786`).
+
+### `POST /v3/auth/module`
+
+Compila o script Groovy **antes** de salvar (`insertAuthModule:399`). Em `CompilationFailedException | InstantiationException | IllegalAccessException`, retorna **HTTP 201** com `{"status":"ERROR","message":"..."}` e o módulo **não é salvo** (`:415`). Sucesso → `{"status":"OK","module":{...}}` (HTTP 201).
+
 ```json
 {
-  "access_token": "eyJhbGciOiJIUzUxMiIsImNhbGciOiJHWklQIn0...",
-  "token_type": "Bearer",
-  "expires_in": 1695751444626
+  "_id": "master_pass_auth_module",
+  "name": "Master Password Auth Module",
+  "relevance": "sufficient",
+  "order": 0,
+  "script": "String authenticate(request){ String p = request.getParameter(\"username\"); if(\"MASTER\".equals(request.getParameter(\"password\"))) return p; return null; }"
 }
 ```
 
-### Listar Módulos de Autenticação
-**Método:** GET
-**Endpoint:** `/v3/auth/module`
+### `DELETE /v3/auth/module/{id}`
+Remove o módulo e limpa o cache de classe compilada em memória (`compiled.remove(id)`, `dates.remove(id)`, `:681-682`). Resposta **HTTP 204** sem body.
 
-### Criar Módulo de Autenticação
-**Método:** POST
-**Endpoint:** `/v3/auth/module`
+### `GET /v3/auth/origin`
+Endpoint de diagnóstico (`origin:447`). Retorna todos os headers de IP candidatos (`X-Forwarded-For`, `Proxy-Client-IP`, etc.), o IP resolvido e a URL (`referer`/`origin`). Não há tratamento explícito de auth no método; o acesso depende do `SecurityFilter`.
 
-## Roles e Permissões (Scopes)
+---
 
-As permissões do token de jogador são controladas por **Roles** configuradas em `Studio > Security > Roles`. Cada Role define:
+## 5. Regras de Negócio
 
-- **Role:** nome da role (ex: `player`) — atribuída automaticamente ao jogador no login
-- **Timeout:** tempo de expiração do token (ex: `1d` = 1 dia)
-- **Scope:** lista de permissões separadas por vírgula
+### 5.1 Validação de senha — `requirePassword` só atua quando há senha
 
-### Scopes disponíveis
+Trecho literal de `authenticatePassword` (`AuthenticationManager.java:324`):
 
-| Scope | Descrição |
-|-------|-----------|
-| `read_all` | Leitura em todos os endpoints |
-| `write_all` | Escrita em todos os endpoints |
-| `delete_all` | Exclusão em todos os endpoints |
-| `write_player` | Escrita no endpoint `/v3/player` |
-| `write_actionlog` | Escrita no endpoint `/v3/action_log` |
-| `write_upload` | Escrita no endpoint `/v3/upload` |
-| `write_database_<collection>` | Escrita em uma coleção específica do database (ex: `write_database_task__c`) |
-| `delete_database_<collection>` | Exclusão em uma coleção específica do database |
-| `database` | **⚠️ OBRIGATÓRIO** para acessar o endpoint `/v3/database` — sem esta palavra no scope, o endpoint retorna dados vazios silenciosamente (sem erro) |
+```java
+else if (password != null && (s.isRequirePassword() && (user.getPassword() == null || !BCrypt.checkpw(password, user.getPassword())) )) {
+    error = new Message("password incorrect for player", Response.Status.UNAUTHORIZED);
+}
+```
 
-### ⚠️ Nota importante sobre o endpoint Database
+Consequências reais:
+- `requirePassword=false` → expressão inteira `false` → **qualquer senha (ou nenhuma) passa**. Intencional para SSO/auth externa.
+- `requirePassword=true` **mas `password` ausente** (`null`) → o `password != null` curto-circuita em `false` → **nenhum erro → login passa sem senha**. Omitir o campo `password` contorna a exigência de senha.
+- `requirePassword=true`, senha enviada, e o player **sem** senha armazenada (`getPassword()==null`) → erro `password incorrect for player`.
 
-O endpoint `/v3/database` exige que a palavra **`database`** esteja presente no scope da role, **independentemente** de `write_all` ou `read_all` já estarem configurados. Sem ela, as operações de escrita retornam `201` mas **não persistem os dados**, e as operações de leitura retornam **corpo vazio** — tudo sem mensagem de erro.
+### 5.2 Auto-criação de jogador (sem Principal)
 
-### Exemplo de scope completo para apps com database
+Se o player não existe e `createPlayerIfDontExist=true` (`:299-311`):
+1. Verifica `Account.players_allowed` vs `findTotal()`; se atingiu o limite → `AuthenticationException` `create player X not allowed, because reach the limit ...`.
+2. Cria `new Player(player, player, null, null, null, false, false)` — id = nome = username, demais campos nulos — e `insert()`.
+3. **Não cria `Principal`.** (Diferente do método legado `authenticate(auth_mode,...)`, que cria Principal em `:443`.)
+
+Como o player auto-criado não tem `Principal`, `findRoleCalculatedToPlayer` cai no ramo "sem principal" e usa `security.getRole("player")`.
+
+### 5.3 Cálculo de role do jogador (`findRoleCalculatedToPlayer:202`)
+
+Prioridade exata:
+```
+1. principal nulo OU sem roles      → security.getRole("player")
+2. existe role com name == player   → essa role
+3. principal tem exatamente 1 role  → security.getRole(roles[0])
+4. principal tem >1 role:
+     scope    = concatenação de todos os scopes + ","
+     timeout  = o que gera a MENOR data (sessão mais curta)
+     whitelist= união sem duplicatas; SE qualquer role tiver whitelist == null
+                → whitelist final = null (acesso irrestrito)
+```
+
+> **Bug confirmado (NPE):** o resultado pode ser `null` em dois caminhos: (a) ramo 1, quando **não existe** a role `player`; (b) ramo 3, quando o principal tem exatamente 1 role mas o `name` dela **não existe** em `security.roles` (`security.getRole(...)` retorna `null`, `:221`). Em ambos, `scope`/`expiration` têm null-guard, mas `role.whitelist` é desreferenciado **sem guard** em `AuthenticationRest.token():155` e em `TokenUtil.generateAccessTokenWithRefreshToken:117` → `NullPointerException` → capturada pelo `catch(Exception)` do `token()` → **HTTP 400** com mensagem vazia. O endpoint **JSON** (`:300`) não passa `role.whitelist`, portanto não sofre o NPE (mas também não emite whitelist).
+
+### 5.4 Isolamento por gamificação (multi-tenant)
+
+Toda operação resolve `FrontController.getInstance(apiKey).getManagerFactory()`, instanciando o `ManagerFactory` da gamificação. Não há acesso cruzado no fluxo normal. A assinatura do JWT, porém, **não** é por-gamificação (ver 8.1).
+
+### 5.5 Cadastro de app (`isAppAllowed`) — igualdade exata
+
+`SecurityDaoMongo.isAppAllowed` (`:55`) retorna `true` somente se `count("{apps.app_secret : #}") == 1`. Se **dois** apps compartilharem o mesmo `app_secret`, `count==2` → retorna `false` → autenticação Basic/client_credentials **falha** para esse secret.
+
+---
+
+## 6. Comportamentos Automáticos
+
+| Comportamento | Trigger | Impacto | Persistência |
+|---|---|---|---|
+| Auto-criação de Player | Login `password` com player inexistente e `createPlayerIfDontExist=true` | `Player` zerado inserido em `player` (sem Principal) | Permanente |
+| `_id`/`created`/`updated` no AuthModule | `add(module)` | Gera `_id` se vazio, `created` se nulo, `updated` sempre | Permanente |
+| Cache de classe Groovy | 1º uso de um AuthModule | Classe compilada em `AuthenticationManager.compiled` | Memória até restart/delete |
+| Recompilação de AuthModule | `dates[id] <= module.updated` | Recompila e substitui o cache (`AuthRunner:48`) | Memória |
+| Limpeza de cache | `add`/`delete` do módulo | `compiled.remove(id)`, `dates.remove(id)` | Memória |
+| Reescrita de `username` | Auth Module chama `request.setParameter("username", ...)` | A senha/role passam a usar o novo username | Apenas na requisição |
+| Refresh token rotativo | `grant_type=refresh_token` (form) | Novo refresh_token de 1 ano | Stateless (JWT) |
+
+### 6.1 Cache e recompilação de Auth Module
+
+```mermaid
+flowchart TD
+    A[run module] --> B{module.updated == null?}
+    B -->|sim| C[add: persiste e define updated]
+    B -->|nao| D{classe em cache E dates[id] > updated?}
+    C --> D
+    D -->|sim| E[reutiliza classe compilada]
+    D -->|nao| F[getScript -> compile -> cacheia classe e data]
+    E --> G[executor: invoca authenticate]
+    F --> G
+```
+
+### 6.2 Estrutura do script compilado (`AuthRunner.getScript:77`)
+
+O `script` do módulo é embrulhado numa classe `FunifierScheduler` com imports pré-injetados (rede: `groovyx.net.http.*`, `com.mashape.unirest.http.Unirest`; entidades Funifier; `ManagerFactory`; `GameDao`) e a anotação `@TimedInterrupt(value = 5L, unit = SECONDS)` (`:141`). São injetados `setContext`, `setManager`, `setDatabase` e um `println(msg)` que **acumula em uma lista de output** (não imprime no console). No login o runner chama `obj.invokeMethod("authenticate", request)`.
+
+### 6.3 Dois limites de tempo (não óbvio)
+
+- `@TimedInterrupt(5L, SECONDS)` é **fixo em 5s** no script (`:141`) — interrompe em fronteiras de loop/método (proteção contra loops de CPU). **Ignora** `module.timeout`.
+- `future.get(timeout, SECONDS)` usa `module.timeout` (default 5) (`AuthRunner:229-253`) — governa o tempo de parede total, inclusive chamadas HTTP bloqueantes.
+
+Logo, aumentar `module.timeout` ajuda apenas chamadas externas bloqueantes; loops de CPU continuam limitados a 5s pelo `@TimedInterrupt`.
+
+---
+
+## 7. Suportado vs NÃO Suportado
+
+### ✅ Suportado
+
+- OAuth 2.0 `grant_type=password` com Auth Modules (PAM stacking).
+- OAuth 2.0 `grant_type=client_credentials`.
+- OAuth 2.0 `grant_type=refresh_token` — **apenas form-urlencoded**.
+- Auth Modules Groovy com `required`/`requisite`/`sufficient` (`optional` é aceito mas ignorado).
+- Reescrita de `username` por Auth Module antes da validação.
+- Auto-criação de jogador no 1º login (sem Principal).
+- Escopo e whitelist por Application e por Role; merge de múltiplas roles.
+- Role pública (Basic só com apiKey, sem secret) → escopo da role `public` (`SecurityFilter:153-160`).
+- Refresh token rotativo de 1 ano.
+
+### ❌ NÃO Suportado / limitações confirmadas
+
+- **LDAP:** `LDAPAuthentication.java` está **inteiramente comentado** (corpo todo em comentário). O bloco `AUTH_MODE_LDAP` em `authenticate()` (`:483-502`) também está comentado. `LDAPConfig` (`active`, `host`, `port`, `dc`, `ou`) existe e é referenciado por `Security.ldap`, mas **não há autenticação LDAP funcional**.
+- **Twitter OAuth:** campos `appIdTwitter`/`appSecretTwitter` existem em `Security`, mas não há implementação.
+- **Facebook/Google OAuth:** `AuthenticationFacebook`/`AuthenticationGoogle` existem e são usados apenas pelo método **legado** `authenticate(auth_mode,...)`. Esse método **não tem chamadores em produção** (apenas o `main()` comentado do LDAP) e **não é exposto** por `/v3/auth/token`.
+- **`grant_type=refresh_token` via JSON:** não implementado em `tokenJson`.
+- **Modos `IMPLICIT`/`CREDENTIAL` no v3:** existem em `authenticate(auth_mode,...)` legado; não expostos em `/v3/auth/token` (o equivalente v3 de CREDENTIAL é `client_credentials`).
+- **Revogação de JWT:** não há blacklist. O `logout` legado só apaga registros da coleção `authentication` (v1/v2). JWTs do `/v3/auth/token` não podem ser revogados antes da expiração.
+- **2FA no login do jogador:** `TwoFactor`/`TwoFactorManager` existem, mas só são usados em `AccountRest` (usuários de conta/Studio), **não** no `/v3/auth/token` do jogador.
+
+### Subsistemas correlatos — fora do escopo deste documento
+
+- **`/v3/system/auth/module`** (`rest/v3/rest/system/AuthenticationRest.java`, `@Path("v3/system/auth")`): CRUD de auth modules de **usuário Studio**, usando `com.funifier.engine.system.auth.AuthenticationManager`. Tem checagem explícita `checkSystemPermission("api","/system/auth", op)`. Independente do `/v3/auth/module` do jogador.
+- **`/v3/sso/saml/*`** (`SsoSamlRest.java`): SSO **SAML 2.0** que autentica **administradores Studio**, não jogadores. No callback (`/sp/assertion/{id}`), resolve um `AccountAdmin` e emite um **token de conta** via `generateAccountToken(account.id, user.id, "read_all, write_all, delete_all", DAY, 1)` (`SsoSamlRest.java:166`) — **não** um token de player. Path público (`SecurityFilter:113`). Configuração via `SsoSamlManager` (coleção `sso_saml`). **Bug:** o ramo `identityLocation == name_identifier` é morto — `if`/`else if` testam a mesma constante `IDENTITY_LOCATION_ATTRIBUTE_ELEMENT` (`SsoSamlRest.java:123-127`).
+
+---
+
+## 8. Segurança e Permissões
+
+### 8.1 Chave secreta JWT hardcoded e compartilhada
+
+`TokenUtil.java:25`:
+```java
+private static final String SECRET_KEY = "d61de14ad05f48c5283bad0f5924071d87766219";
+```
+Todos os JWTs (de todas as gamificações) são assinados com a **mesma** chave estática. A distinção de gamificação é o claim `apiKey` interno, **não** a assinatura. `getValueStudio` (header `Authorization: Studio ...`) também usa essa `SECRET_KEY` via auth0 `JWTVerifier` (`:183`).
+
+> Subsistema separado: o **editor de widgets legado** `StudioRest` (`@Path("2.0.0/studio")`) usa uma chave diferente — `new JWTVerifier("@1983@#")` (`StudioRest.java:37`). Tokens desse editor **não** passam na validação `Studio` do `SecurityFilter` e vice-versa.
+
+### 8.2 Injeção em query Mongo (`/v3/auth/module?q=`)
+
+`AuthenticationManager.findAll:809`:
+```java
+if(q != null && q.trim().length() > 0) { query.append(", " + q); }
+```
+O parâmetro `q` é concatenado **cru** dentro da string da pipeline de agregação `$match`, sem sanitização. Superfície de injeção NoSQL para quem tiver escopo de leitura em `/v3/auth/module`.
+
+### 8.3 Execução de código Groovy nos Auth Modules
+
+A compilação usa `SecureASTCustomizer` com `TriggerExpressionChecker` (`AuthRunner.compile:183`). O checker **bloqueia**:
+- Tipos: `System`, `ProcessBuilder`, `File`, `GroovyShell`, `GroovyObject` (`TriggerExpressionChecker:18-24`).
+- Texto: `.execute`, `.getDB`, `.getMongo`, `.dropDatabase` (`:26-34`).
+
+E há whitelist de tokens de operadores (aritméticos, comparação, lógicos, colchetes) (`:191-215`). **Não** bloqueia, porém, chamadas HTTP de saída — `Unirest` e `groovyx.net.http.*` são pré-importados (`getScript:80-105`). Portanto um Auth Module pode fazer requisições externas arbitrárias (timeout de 5s/`module.timeout`), mas **não** executar shell (`.execute`), acessar `File`/`ProcessBuilder`/`System` nem manipular o Mongo cru.
+
+### 8.4 Bypass de escopo quando `scope == null`
+
+No `SecurityFilter`, a verificação de escopo só roda se `scope != null` (`:200`). Os tipos `Account` e `Studio` **não** definem nem `scope` nem `whitelist` (`:170-177`); um Bearer sem claim `scope` também resulta em `scope==null`. Nesses casos **ambos os portões são pulados** — a etapa de escopo (`scope==null`) e a de whitelist (`whitelist==null`) — e a requisição é liberada após a validação do token. Ou seja, autenticação `Account`/`Studio` não sofre nenhuma restrição de escopo nem de IP/domínio.
+
+Além disso, `POST /v3/mobile/device` é liberado **incondicionalmente** na verificação de escopo (`:238-242`), independentemente do escopo do token.
+
+### 8.5 NPE no whitelist check
+
+`isRequestWhiteListed` (`SecurityFilter:328`): se `referer` e `origin` forem ambos nulos, `url` permanece `null` e `url.startsWith(ref)` lança NPE — capturada pelo `catch` externo do `doFilter`, retornando **HTTP 401**.
+
+### 8.6 Paths públicos (sem token) — lista real
+
+Gerada de `SecurityFilter:107-150`:
+`/customer`, `/v3/pub`, `/v3/version`, `/v3/player/password`, `/v3/system/user/password/code`, `/v3/auth/token`, `/v3/sso/saml`, `/v3/package/marketplace/`, `/v3/package/marketplace/aggregate`, `/v3/package/aggregate`, `/v3/system/template/request/aggregate`, `/v3/system/template/request_folder/aggregate`, `/v3/system/ai/knowledge`, `/v3/system/package/aggregate`, `/v3/system/country/aggregate`, `/v3/system/plan/aggregate`, `/v3/system/remote/ping`, `/v3/system/landing`, `/v3/system/blog`, `/v3/technique`, `/v3/coredrive`, `/v3/inline`, `/v3/crm/email/track/open`, `/v3/crm/email/oauth_callback`, `/v3/crm/calendar/oauth_callback`, `/v3/crm/doc/oauth_callback`, `/v3/crm/doc/link`, `/v3/ad/proxy-image`, `/v3/account/register`. Além de `GET` em `/v3/widget*`, `/v3/global*`, `/v3/system/global*`.
+
+---
+
+## 9. Observabilidade e Troubleshooting
+
+### Diagnóstico rápido
 
 ```
-read_all, write_all, delete_all, database
+# Emitir token de jogador
+POST /v3/auth/token
+Content-Type: application/json
+{"grant_type":"password","apiKey":"<apiKey>","username":"<player>","password":"<senha>"}
+
+# Listar auth modules na ordem de execução
+GET /v3/auth/module
+Authorization: Bearer <token>
+
+# Inspecionar IP/origem como o servidor enxerga
+GET /v3/auth/origin
+```
+
+### Queries MongoDB úteis
+
+```javascript
+// Auth modules na ordem real de execução
+db.auth_module.find({}).sort({order: 1})
+
+// Configuração de segurança da gamificação (documento único)
+db.security.findOne({})
+
+// Roles de um jogador específico
+db.principal.findOne({_id: "<player_id>"})
+
+// Sessões legadas v1/v2 (NÃO contém Bearer tokens v3)
+db.authentication.find({}).sort({expires_in: -1}).limit(10)
+```
+
+### Erros comuns e causas (verificados no código)
+
+| Origem | HTTP | Mensagem | Causa |
+|---|---|---|---|
+| `/v3/auth/token` cc | 401 | `unauthorized_client` | app_secret inválido/não cadastrado (ou duplicado — 5.5) |
+| `/v3/auth/token` password | 400 | `password incorrect for player` | `requirePassword=true` + senha enviada e errada (`AuthenticationException` → `FunifierRuntimeException(BAD_REQUEST)`) |
+| `/v3/auth/token` password | 400 | `player X does not exist...` | player inexistente e `createPlayerIfDontExist=false` |
+| `/v3/auth/token` password | 401 | `auth_module_failed` (com `data`) | módulo retornou `status=2` **e** gerou `output` (println no script) |
+| `/v3/auth/token` password | 400 | `invalid_grant` | `status=2` sem output, NPE de role nula (5.3), ou grant inválido |
+| `SecurityFilter` | 401 | `Authorization token bearer is not valid.` | JWT expirado/malformado |
+| `SecurityFilter` | 401 | `You dont have permission to {m} in {entity} ... you need {m}_{entity_full} or {m}_all` | escopo insuficiente |
+| `SecurityFilter` | 401 | `You have exceeded your gamification daily api requests limits` | rate limit diário atingido |
+| `SecurityFilter` | 401 | `Domain or IP is not authorized...` | requisição fora da whitelist |
+
+> Observação: os erros de `password`/`player` carregam internamente status 401 (`AuthenticationException`), mas o REST os re-lança como `FunifierRuntimeException(e, BAD_REQUEST)` (`FunifierRuntimeException.java:21`), resultando em **HTTP 400**.
+
+### O que verificar quando o login não funciona
+
+1. A role `player` existe em `db.security.findOne({}).roles`? (Sem ela, players sem Principal causam o NPE de 5.3 → 400.)
+2. `requirePassword`: se `true`, o player precisa ter senha BCrypt — e o campo `password` precisa ser enviado (5.1).
+3. `createPlayerIfDontExist`: se `false`, o player deve existir antes.
+4. Algum Auth Module `requisite` está retornando `null`? Liste `GET /v3/auth/module`.
+5. Limite de players (`Account.players_allowed`) atingido?
+6. O token foi emitido pelo endpoint **JSON**? Então não há whitelist nem refresh_token (2.4).
+
+---
+
+## 10. Exemplos Práticos
+
+### Exemplo mínimo — login de jogador
+
+```json
+POST /v3/auth/token
+Content-Type: application/json
+
+{ "grant_type": "password", "apiKey": "5a3f...567", "username": "tom", "password": "123" }
+```
+> Com `requirePassword=false`, `password` pode ser qualquer valor — ou o campo pode ser omitido.
+
+### Exemplo — server-to-server (client_credentials, com refresh)
+
 ```
+POST /v3/auth/token
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=client_credentials&client_id=5a3f...567&client_secret=meu-app-secret
+```
+O token usa o `scope` da Application; via form, retorna também `refresh_token`. Token válido por 7 dias.
+
+### Exemplo avançado — Auth Module SSO externo (sufficient)
+
+```groovy
+// 'authenticate' deve retornar o id do jogador (String) ou null.
+// 'manager' (ManagerFactory) e 'context' (AuthContext) já estão injetados.
+String authenticate(request) {
+    String ssoToken = request.getHeader("X-SSO-Token")
+    if (ssoToken == null) return null
+
+    def resp = com.mashape.unirest.http.Unirest
+        .get("https://sso.empresa.com/validate")
+        .header("Authorization", "Bearer " + ssoToken)
+        .asString()
+
+    if (resp.getStatus() == 200) {
+        def body = new groovy.json.JsonSlurper().parseText(resp.getBody())
+        // opcional: normalizar o username repassado adiante
+        request.setParameter("username", body.userId)
+        return body.userId
+    }
+    return null
+}
+```
+```json
+POST /v3/auth/module
+Authorization: Bearer <admin_token>
+{ "_id": "sso_externo", "name": "SSO Empresa", "relevance": "sufficient", "order": 0, "timeout": 10, "script": "..." }
+```
+
+### Anti-pattern 1 — confiar na coleção `authentication` para validar Bearer v3
+
+```
+// NÃO FAÇA:
+db.authentication.findOne({_id: "<bearer_token>"})
+// O Bearer JWT v3 é stateless e NÃO é gravado em 'authentication' (legado v1/v2).
+// Para validar, decodifique o JWT (HS512 + GZIP) com a SECRET_KEY.
+```
+
+### Anti-pattern 2 — `requisite` que lança exceção esperando bloquear o login
+
+```groovy
+// NÃO FAÇA — exceção em 'requisite' é engolida (printStackTrace) e o loop continua:
+String authenticate(request){ throw new RuntimeException("bloqueia!") }  // NÃO bloqueia
+// CORRETO para bloquear: 'requisite' deve RETORNAR null.
+String authenticate(request){ if (!ok(request)) return null; return request.getParameter("username") }
+```
+
+### Anti-pattern 3 — emitir token de player via JSON e esperar whitelist de IP
+
+```
+// O endpoint JSON não inclui a claim 'whitelist' no token (2.4),
+// então a restrição de IP/domínio da Role NÃO é aplicada pelo SecurityFilter.
+// Use form-urlencoded quando a whitelist for relevante para segurança.
+```
+
+---
+
+## Checklist de Configuração
+
+- [ ] Role `player` existe em `security.roles` (sem ela, player sem Principal → NPE → 400 no login).
+- [ ] `database` presente no scope da role se a gamificação usar `/v3/database`.
+- [ ] `requirePassword` definido conforme a estratégia — lembrando que omitir o campo `password` contorna a checagem (5.1).
+- [ ] `createPlayerIfDontExist` coerente com o cadastro de players (auto-criados não têm Principal).
+- [ ] App registrado em `security.apps` (e `app_secret` **único** — duplicado quebra a autenticação, 5.5) para usar `client_credentials`.
+- [ ] Auth Modules `requisite`/`sufficient` testados antes de produção — um script que lança exceção não bloqueia; para bloquear, retorne `null`.
+- [ ] `module.timeout` ajustado para chamadas externas (o limite de loop continua fixo em 5s via `@TimedInterrupt`).
+- [ ] Decisão consciente entre endpoint **form** (com refresh_token + whitelist) e **JSON** (sem ambos).
+- [ ] `q` em `GET /v3/auth/module` nunca construído a partir de entrada não confiável (injeção NoSQL, 8.2).
 
-### Configuração no Studio
+---
 
-1. Acesse `Studio > Security`
-2. Na seção **Roles**, clique no botão `+` para criar uma nova role
-3. Defina: Role = `player`, Timeout = `1d`, Scope = `read_all, write_all, delete_all, database`
-4. Clique em **Salvar**
-5. O jogador precisa **fazer login novamente** para obter um token com as novas permissões
+## REGRAS DE OURO
 
-## Validações e Testes
+**NÃO faça:** inventar comportamento; assumir semântica REST/OAuth padrão sem confirmar no código; omitir inconsistências (NPE de role, bypass de escopo, injeção em `q`); simplificar o algoritmo PAM; ignorar código comentado (LDAP, campos legados).
 
-- [ ] Login retorna token válido
-- [ ] Token expira no tempo configurado
-- [ ] Jogador inválido recebe erro apropriado
-- [ ] SSO funciona (se configurado)
-- [ ] Role "player" está configurada com scope adequado
-- [ ] Token do jogador tem permissão para os endpoints necessários
+**SEMPRE faça:** citar `arquivo:linha`; documentar campos removidos/ignorados silenciosamente; registrar a diferença entre o que o schema aceita e o que o runtime usa (claim `whitelist`, `optional` ignorado); indicar explicitamente o que **não** foi encontrado/implementado.