funifier-mcp 0.2.25 → 0.2.27

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

@@ -1,169 +1,731 @@
-# Security (Segurança)
+# `security`
 
-**Acesso Studio:** Gamification Settings → "Mais" → Security → "Change your gamification security settings"
-**Armazenamento:** Coleção `security`, documento com `_id` = API Key da gamificação
+**Acesso Studio:** Funifier Studio → Security (cadastro de **Apps** e **Roles**). Não há rota Studio dedicada confirmável no backend.
+**API Endpoint:** `/v3/database/security/{_id}` — gerenciado pelo `DatabaseRest` genérico. **Não existe `SecurityRest`.** Endpoints correlatos: `/v3/auth/token`, `/v3/auth/module`.
+**Coleção MongoDB:** `security`
 
-## Estrutura do Documento
+> Engenharia reversa baseada no código de `funifier-service` (`com.funifier.engine.security.*`, `com.funifier.rest.v3.filter.SecurityFilter`, `com.funifier.engine.auth.*`, `com.funifier.rest.v3.rest.DatabaseRest`, `com.funifier.rest.v3.rest.AuthenticationRest`, `com.funifier.rest.v3.TokenUtil`, `com.funifier.rest.v3.AuthBean`). Onde a documentação anterior divergia do código, o código prevalece — as divergências estão sinalizadas ao longo do texto.
 
-```json
-{
-  "_id": "API_KEY_DA_GAMIFICACAO",
-  "roles": [
-    { "name": "public", "scope": "read_all", "timeout": "" },
-    { "name": "player", "scope": "read_all, write_all, delete_all, database", "timeout": "" }
-  ],
-  "apps": [
-    { "name": "Nome do App", "app_secret": "GUID_GERADO", "scope": "read_all, write_all, delete_all, database" }
-  ]
-}
-```
+---
+
+## 1. Visão Geral
 
-## Roles
+A coleção `security` guarda **um documento de configuração de segurança por gamificação**. No Funifier cada gamificação tem seu próprio banco MongoDB, então a coleção `security` daquele banco contém — **por convenção** — um único documento. Essa unicidade **não é imposta pelo código**: a leitura usa `findOne()` sem filtro (`SecurityDaoMongo.find()`) e a escrita é um `save()` por `_id` (ver seção 2.1). Documentos extras podem coexistir e causar comportamento ambíguo.
 
-Definem o nível de acesso dos tokens Bearer (jogadores logados) e Basic (acesso público).
+O documento concentra:
 
-### Campos
-- `name` — Identificador da role (ex: `public`, `player`, `admin`)
-- `scope` — Permissões separadas por vírgula
-- `timeout` — Tempo de expiração do token (ex: `7d`, `1h`). **⚠️ NÃO usar string vazia `""`** — causa NPE no auth. Omitir o campo ou usar `null` para timeout padrão (7 dias).
+- **`apps`** — aplicações servidoras com `app_secret`, `scope` e `whitelist` (autenticação Basic / `client_credentials`).
+- **`roles`** — papéis de jogador com `scope`, `timeout` (validade do token) e `whitelist` (autenticação `password`).
+- **`requirePassword`**, **`createPlayerIfDontExist`** — comportamentos de login de jogador.
+- **`timeZone`** — fuso horário consumido por challenges/bônus/conquistas.
+- **`inlineEditable`** — edição inline no Studio.
 
-### Scopes Disponíveis
-| Scope | Descrição |
-|-------|-----------|
-| `read_all` | Leitura em todas as coleções |
-| `write_all` | Escrita em todas as coleções |
-| `delete_all` | Exclusão em todas as coleções |
-| `database` | **Obrigatório** para acessar `/v3/database`. Sem ele, POST retorna 201 mas não persiste |
+O documento é **lido em tempo de request** por:
 
-### Roles Comuns
-- **`public`** — `read_all, write_database_signup__c` — Para acesso não autenticado (signup, landing page). Usa token Basic. Precisa de `write_database_signup__c` para o signup pattern funcionar.
-- **`player`** — `read_all, write_all, delete_all, database` — Para usuários logados. Usa token Bearer.
+1. **`SecurityFilter`** — filtro de servlet que intercepta toda requisição `/v3/**` e decide passar ou retornar `401` (seção 2.2). Lê `roles` (role `public`) e `apps` (`scope`/`whitelist`).
+2. **`AuthBean.getScope()`** — recalcula o scope efetivo para `/v3/database` (seção 4).
+3. **`AuthenticationRest` (`/v3/auth/token`)** — emite tokens Bearer JWT a partir de `apps`/`roles` (seção 2.4).
+4. **Managers de domínio** — `timeZone` (`ChallengeManager`, `LastMileManager`, `BonusManager`, `AchievementManager`), `inlineEditable` (`FrontController.isInline`, `InlineManager`), `createPlayerIfDontExist` (`AuthenticationManager.createIfDontExist`, usado na ingestão de action logs).
 
-### ⚠️ Lição Crítica
-A palavra **`database`** deve estar literalmente no scope para que `/v3/database` funcione. Mesmo com `write_all` e `read_all`, sem `database` as operações falham silenciosamente.
+> **Importante (divergência com a documentação anterior):** existe no código um método `AuthenticationManager.authenticate(auth_mode, player, app_secret, password, …)` com os modos `IMPLICIT`, `CREDENTIAL`, `LDAP`, `FACEBOOK`, `GOOGLE`, validação de `websites` e auto-criação de player no login. **Esse método não é chamado por nenhum endpoint** (código órfão — ver seção 2.6 e 7). A documentação anterior descrevia esse fluxo como se fosse o caminho vivo de autenticação de jogador; ele **não** é alcançável.
 
-## Apps
+---
 
-Apps geram tokens Basic não-expirantes para uso em triggers, endpoints públicos e integrações server-side.
+## 2. Arquitetura e Fluxos
 
-### Campos
-- `name` — Nome descritivo do app
-- `app_secret` — GUID gerado pelo Funifier (via `/v3/util/guid/new`)
-- `scope` — Permissões (mesmo formato das roles)
+### 2.1 Persistência — via `DatabaseRest` genérico (NÃO há full-replace)
+
+Não existe `SecurityRest`. A entidade está registrada no enum de roteamento como `Entity.SECURITY("security", Security.class)` e é gravada/lida pela coleção genérica do `DatabaseRest`.
+
+`SecurityManager.update()` e `SecurityDaoMongo.update()` (que fazem `c.remove(); c.save(security);` — apagar **toda** a coleção e reinserir) **são código morto no caminho Java**: o único `.update(security)` no projeto é a própria definição/duplicata comentada, e nenhum endpoint o invoca. Ressalva: o `grep` cobre apenas o código Java compilado — um script Groovy (trigger/auth module) que chame `manager.getSecurityManager().update(...)` **dispararia** o `c.remove() + c.save()` destrutivo (apaga toda a coleção `security`). Evite expor essa chamada em scripts.
+
+A escrita real é a do `DatabaseRest`:
 
-### Token Basic do App
 ```
-Basic base64(API_KEY + ":" + APP_SECRET)
+[PUT /v3/database/security]  → DatabaseRest.update()
+1. valida scope contém "database" (Application.SCOPE_DATABASE) e collection.length > 3
+2. se body não tem _id → gera Guid.newShortGuid()   ← cria documento avulso!
+3. TriggerManager.execute(..., "security", EVENT_BEFORE_UPDATE, player)
+4. jongo.getCollection("security").save(o)            ← upsert por _id (Jongo)
+5. TriggerManager.execute(..., "security", EVENT_AFTER_UPDATE, player)
+6. AuditManager.log("security", EVENT_UPDATE, authBean, o)
 ```
 
-Exemplo:
-```javascript
-var basicToken = 'Basic ' + btoa('69ab1a9a607db81962b92cd2:69ab3566607db81962b9686e');
+Consequências reais do `save(o)`:
+
+- **É um upsert do documento inteiro pelo `_id`.** Campos omitidos no PUT **somem daquele documento** (é substituição do documento, não merge/patch). A advertência "PUT parcial apaga campos" continua válida — porém **o motivo não é** "apaga a coleção inteira".
+- **NÃO apaga os demais documentos da coleção.** Se você gravar com um `_id` diferente, cria um **segundo** documento `security`. Como `find()` usa `findOne()` sem filtro, qualquer documento pode "vencer".
+- **POST e PUT geram `_id` automático** quando ausente (`Guid.newShortGuid()`), o que produz documentos `security` órfãos.
+
+Leitura interna (`SecurityDaoMongo.find()`):
+
+```java
+Security s = c.findOne().as(Security.class);
+return s != null ? s : new Security();   // NUNCA retorna null
+```
+
+> `find()` **nunca retorna null** — se a coleção estiver vazia retorna `new Security()`, cujos defaults de campo são `requirePassword=false`, `createPlayerIfDontExist=true`, `timeZone=null`. (A documentação anterior afirmava retorno `null` — incorreto.)
+
+### 2.2 Pipeline de autorização — `SecurityFilter.doFilter()`
+
+Executado a cada requisição HTTP. Tipos de auth reconhecidos: `Basic`, `Account`, `Studio`, `Bearer`.
+
+#### Fluxo de autorização — `SecurityFilter.doFilter`
+
+```mermaid
+flowchart TD
+    A[Request /v3/**] --> B{method == OPTIONS?}
+    B -- sim --> PASS[doFilter -> segue]
+    B -- nao --> C[apikey = AuthBean.getApiKey]
+    C --> D{apikey != null?}
+    D -- sim --> E[StatisticManager.newApiRequest]
+    E --> F{limite diario ok?}
+    F -- nao --> R401A[401 exceeded daily api requests]
+    F -- sim --> G
+    D -- nao --> G{path em whitelist publica?}
+    G -- sim --> PASS
+    G -- nao --> H{GET widget/global/system.global?}
+    H -- sim --> PASS
+    H -- nao --> I{tipo de Authorization}
+    I -- Basic publico --> J[scope = role public.scope]
+    I -- Basic c/ secret --> K[authBasic; scope=app.scope; whitelist=app.whitelist]
+    I -- Basic invalido --> ERR[errorMessage]
+    I -- Account --> L[authAccount]
+    I -- Studio --> M[authStudio]
+    I -- Bearer --> N[authBearer; scope=token.scope; whitelist=token.whitelist]
+    I -- nenhum --> ERR
+    J --> O{whitelist != null?}
+    K --> O
+    N --> O
+    O -- sim --> P{IP ou URL na whitelist?}
+    P -- nao --> R401B[401 Domain or IP is not authorized]
+    P -- sim --> Q
+    O -- nao --> Q{scope != null?}
+    Q -- sim --> S[avalia hierarquia de scope]
+    Q -- nao --> PASS
+    S --> T{permitido?}
+    T -- sim --> PASS
+    T -- nao --> ERR
+    ERR --> U[newBadRequest + 401 errorMessage]
 ```
 
-## Como Criar via API (sem Studio UI)
+Sequência exata:
 
-### 1. Obter token de autenticação do Studio
-O Studio armazena o token em `localStorage` com a chave `marketplace_authorization`:
-```javascript
-var auth = localStorage.getItem('marketplace_authorization');
-// Retorna: "Bearer eyJ..."
+```
+1. OPTIONS → doFilter (preflight CORS), sem validação
+2. apikey = AuthBean.getApiKey(Authorization)
+3. entity      = path sem "/v3/"; corta no primeiro "/"
+   entity_full = path sem "/v3/", com "/" trocado por "_"
+4. Estatística: se apikey != null → SystemFactory.getStatisticManager(apikey).newApiRequest(method, entity)
+   → retorno false → 401 "You have exceeded your gamification daily api requests limits"
+5. Paths públicos (passa sem auth) — startsWith de:
+   /customer, /v3/pub, /v3/version, /v3/player/password,
+   /v3/system/user/password/code, /v3/auth/token, /v3/sso/saml,
+   /v3/package/marketplace/aggregate, /v3/package/marketplace/, /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
+6. GET /v3/widget | /v3/global | /v3/system/global → passa sem auth
+7. Por tipo de token (Authorization "contém" a palavra):
+   - Basic público (só apiKey, sem secret) → authPublic() true → scope = role "public".scope (se a role existir)
+   - Basic com secret → authBasic() → se inválido errorMessage; se válido scope=app.scope, whitelist=app.whitelist
+   - Account → authAccount() (AccountManager.isAppSecretAllowed)
+   - Studio → authStudio() (TokenUtil.getValueStudio != null) — usa lib auth0 JWTVerifier
+   - Bearer → authBearer() (TokenUtil.getValue "apiKey" ou "account" != null); scope/whitelist do token
+   - nenhum → errorMessage "Need to inform a type of authentication. E.g. Basic, Studio or Bearer."
+8. Se whitelist != null → isRequestWhiteListed() (seção 5); se não → 401 "Domain or IP is not authorized..."
+9. Se scope != null → avalia hierarquia (2.3)
+10. errorMessage != null → newBadRequest + 401 errorMessage
+11. caso contrário → doFilter (segue)
 ```
 
-### 2. Gerar GUID para App Secret
+Notas:
+
+- **Account** com Authorization não tem token JWT; `AuthBean.getApiKey()` retorna `null` para tipo `Account` na versão estática (linha 45) — daí a estatística pode não ser registrada para Account.
+- O `try/catch` global converte qualquer exceção (inclusive NPE) em `401` com `e.getMessage()`.
+
+### 2.3 Avaliação hierárquica de scope (`SecurityFilter`)
+
 ```
-GET https://service2.funifier.com/v3/util/guid/new
-Authorization: Bearer <studio_token>
+scope = scope.replaceAll(" ", "")        // remove TODOS os espaços
+list  = scope.split(",")
+m     = GET→"read" | POST→"write" | PUT→"write" | (outro)→method.toLowerCase()  // DELETE→"delete"
+
+allow_all     = scope.indexOf(m + "_all")  != -1          // ex.: read_all
+allow_full    = list.contains(m + "_" + entity_full)      // ex.: delete_swap_metodo_123
+// fallback só 2 níveis (apesar do comentário "menos n"):
+allow_full_m1 = list.contains(m + "_" + <entity_full sem último _segmento> + "_all")  // delete_swap_metodo_all
+allow_full_m2 = list.contains(m + "_" + <dois segmentos a menos> + "_all")            // delete_swap_all
+
+PASSA se (allow_all || allow_full || allow_full_m1 || allow_full_m2)
 ```
-Retorna: `{ "guid": "69ab3566607db81962b9686e" }`
 
-### 3. Criar/Atualizar Security Document
+#### Hierarquia de scope — exemplo `DELETE /v3/swap/metodo/123`
+
+```mermaid
+flowchart LR
+    A["entity_full = swap_metodo_123<br/>m = delete"] --> B{delete_all?}
+    B -- sim --> P[passa]
+    B -- nao --> C{delete_swap_metodo_123?}
+    C -- sim --> P
+    C -- nao --> D{delete_swap_metodo_all?}
+    D -- sim --> P
+    D -- nao --> E{delete_swap_all?}
+    E -- sim --> P
+    E -- nao --> X[401 sem permissao]
 ```
-PUT https://service2.funifier.com/v3/database/security
-Authorization: Bearer <studio_token>
-Content-Type: application/json
 
-{
-  "_id": "API_KEY",
-  "roles": [...],
-  "apps": [...]
-}
+Exceções (avaliadas só para `POST`, depois da hierarquia):
+
+- `POST /v3/action/log` com scope contendo `write_actionlog` → passa mesmo sem `write_all`.
+- `POST /v3/mobile/device` → passa sem verificação de scope.
+
+Mensagem de negação: `"You dont have permission to {m} in {entity} endpoint, you need {m}_{entity_full} or {m}_all access to do it"`.
+
+> **Camada dupla para `/v3/database`:** o `SecurityFilter` valida `read_all`/`write_all`/`delete_all` (ou os hierárquicos `*_database_all`) usando `entity = "database"`. **Além disso**, o próprio `DatabaseRest` exige que o scope contenha `database`. Logo, um app de servidor típico usa `read_all,write_all,delete_all,database`.
+
+### 2.4 Emissão de token — `POST /v3/auth/token`
+
+#### Emissão de token Bearer — `/v3/auth/token`
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant AuthenticationRest
+    participant AuthenticationManager
+    participant SecurityDaoMongo
+    participant TokenUtil
+
+    Client->>AuthenticationRest: POST /v3/auth/token (grant_type)
+    alt client_credentials
+        AuthenticationRest->>AuthenticationManager: isAppSecretAllowed(client_secret)
+        AuthenticationManager->>SecurityDaoMongo: isAppAllowed (count == 1?)
+        SecurityDaoMongo-->>AuthenticationManager: true/false
+        AuthenticationRest->>AuthenticationManager: findApplication(secret)
+        AuthenticationManager-->>AuthenticationRest: Application{scope, whitelist}
+        AuthenticationRest->>TokenUtil: generateToken(apiKey, secret, scope, 7 dias, whitelist)
+        TokenUtil-->>AuthenticationRest: JWT HS512+GZIP
+        AuthenticationRest-->>Client: {access_token, refresh_token, token_type, expires_in}
+    else password
+        AuthenticationRest->>AuthenticationManager: authenticateModules(req) (Groovy/PAM)
+        AuthenticationManager-->>AuthenticationRest: status 0|1|2
+        AuthenticationRest->>AuthenticationManager: authenticatePassword(player, password) (se status 0)
+        AuthenticationRest->>AuthenticationManager: findRoleCalculatedToPlayer(player)
+        AuthenticationManager-->>AuthenticationRest: Role{scope, timeout, whitelist}
+        AuthenticationRest->>TokenUtil: generateToken(apiKey, player, scope, role.timeout||7d)
+        AuthenticationRest-->>Client: {access_token, refresh_token, token_type, expires_in}
+    else refresh_token
+        AuthenticationRest->>TokenUtil: accessTokenWithRefreshToken(refresh)
+        AuthenticationRest-->>Client: novo access_token + refresh_token
+    end
 ```
 
-**⚠️ PUT é upsert** — substitui o documento inteiro. Sempre incluir roles E apps existentes.
+Detalhes por `grant_type` (existem **dois** handlers `/v3/auth/token`: um `application/x-www-form-urlencoded`, outro `application/json`):
+
+| grant_type | Validação | Expiração do access_token | Refresh token |
+| --- | --- | --- | --- |
+| `client_credentials` | `isAppSecretAllowed(secret)` → `findApplication` | **7 dias** (`TimeScale.DAY, 7`) | sim (form) / não (json) |
+| `password` | auth modules (PAM) + `authenticatePassword` | `role.timeout` (ex.: `7d`) ou **7 dias** default | sim (form) / não (json) |
+| `refresh_token` | re-emite a partir do refresh (1 ano) | reconstruída (app 7d / player role.timeout\|7d) | sim |
+
+- O `expires_in` retornado é **timestamp Unix em milissegundos** (`expiration.getTime()`), e **não** segundos — diverge do padrão OAuth2.
+- A variante `application/json` (`tokenJson`) **não** anexa `whitelist` ao token (usa overload sem whitelist) e **não** devolve `refresh_token`. A variante `application/x-www-form-urlencoded` anexa whitelist e devolve refresh token.
+- `/v3/auth/token` está na whitelist de paths públicos do `SecurityFilter` (não exige autenticação prévia).
+
+> **Atenção ao default de 30 dias:** o valor `60*60*24*30` (30 dias) existe **apenas** dentro do método órfão `authenticate(auth_mode, …)` (seção 2.6), que não é chamado. Os tokens emitidos de verdade por `/v3/auth/token` usam **7 dias** (app e player default) ou `role.timeout`.
+
+### 2.5 Cálculo de role do jogador — `findRoleCalculatedToPlayer(player)`
 
-### 4. Verificar
 ```
-GET https://service2.funifier.com/v3/database/security/API_KEY?strict=true
-Authorization: Bearer <studio_token>
+1. principal = coleção "principal".findOne({_id: player})
+2. security  = SecurityDaoMongo.find()        // nunca null
+3. se principal == null OU principal.roles vazio → role = security.getRole("player")
+4. senão se security.getRole(player) != null    → role individual por id do player
+5. senão se principal.roles.size() == 1         → role = security.getRole(roles[0])
+6. senão (size > 1) → MERGE:
+   - scope    = concatenação de todos os scopes das roles, separados por ","
+   - timeout  = o de MENOR data de expiração (sessão mais curta vence)
+   - whitelist: união sem duplicatas; se QUALQUER role tiver whitelist null → whitelist final = null (irrestrito)
+   - name = player
 ```
 
-## Navegação no Studio (Browser Automation)
+Observações de runtime:
+
+- Se a role resolvida for `null` (ex.: passo 5 com nome de role inexistente em `security.roles`), o chamador (`TokenUtil`/`AuthenticationRest`) cai no default de scope `read_all,write_actionlog,write_upload` e expiração `+7d` — **mas** acessa `role.whitelist` em seguida, o que provoca **NPE** quando `role == null` no overload com whitelist. Edge case real.
+- `DateUtil.fromKeyword("+" + role.timeout)`: um `timeout` igual a `""` (string vazia) gera `"+"`, que tende a produzir erro/`NPE` na geração do token. **Use `null`/omita o campo, nunca `""`.**
+
+### 2.6 Código órfão (presente, mas NÃO acessível)
+
+`AuthenticationManager.authenticate(String auth_mode, String player, String app_secret, String password, int expiration, String language, String host, String oauth_access_token)`:
+
+- Implementa os modos `IMPLICIT` (valida `websites` via `isWebsiteAllowed`), `PASSWORD`, `CREDENTIAL` (valida `app_secret`), `LDAP` (**bloco inteiro comentado** — o `else if (AUTH_MODE_LDAP…)` casa mas não faz nada → `error` permanece null → "autentica" sem checar nada), `FACEBOOK`/`GOOGLE` (com `// TODO`, sem validação), default de expiração de **30 dias**, e auto-criação de player no login.
+- **Nenhum endpoint chama esse método** (`grep` confirma: somente a versão `authenticate(playerId)` de 1 argumento é usada, em `StudioRest`). Portanto:
+  - **`websites` / `isWebsiteAllowed` não têm caminho vivo** (o único caller Java está dentro desse método órfão).
+  - **Facebook/Google (`AuthenticationFacebook`/`AuthenticationGoogle`) não são acionáveis** (instanciados só aqui).
+  - **LDAP não é acionável** e, mesmo se fosse, o bloco está comentado.
+
+`AuthenticationManager.authenticate(String playerId)` (deprecated, 1 argumento) **é** usado por `StudioRest` para gerar um `access_token` opaco (shortGuid) gravado na coleção `authentication` — um mecanismo de sessão legado, distinto do JWT Bearer.
+
+---
 
-1. Abrir `https://my.funifier.com`
-2. Selecionar a gamificação desejada (botão "Select")
-3. Se gamificação nova, clicar "Começar do Zero" para inicializar
-4. Clicar no nome da gamificação na sidebar (link para `/studio/gamification/me`)
-5. Expandir seção "Mais"
-6. Clicar "Change your gamification security settings"
-7. Na página Security: botão "Apps" expande a seção de Apps, botão "Roles" expande Roles
+## 3. Estrutura dos Objetos
 
-**⚠️ SPA Redirect:** Se a gamificação não foi inicializada (wizard "Escolha o melhor caminho"), qualquer navegação para `/studio/security` redireciona para o wizard. Primeiro clicar "Começar do Zero".
+### 3.1 `Security` — documento raiz (`com.funifier.engine.security.Security`)
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+| --- | --- | --- | --- | --- |
+| `_id` | String | — | por convenção = apiKey | Mapeado por `@JsonProperty("_id")`. `find()` ignora o `_id` (usa `findOne()`). |
+| `created_at` | Date | — | — | Data de criação (não preenchida pelo `DatabaseRest`). |
+| `updated_at` | Date | — | — | Data de atualização (não preenchida pelo `DatabaseRest`). |
+| `requirePassword` | boolean | `false` | — | `true` → valida BCrypt no login `password`. `false` → senha ignorada. |
+| `createPlayerIfDontExist` | boolean | `true` | — | `true` → cria player automaticamente (ver 5). Default de campo é `true`. |
+| `timeZone` | String | `null` | — | Fuso Java (ex.: `America/Sao_Paulo`). Lido por Challenge/LastMile/Bonus/Achievement managers. |
+| `inlineEditable` | boolean | `false` | — | Habilita edição inline no Studio (`FrontController.isInline`, `InlineManager`). |
+| `appIdFacebook` | String | — | — | Config OAuth Facebook. **Sem consumidor vivo de auth** (ver 2.6/7). |
+| `appSecretFacebook` | String | — | — | idem. |
+| `appIdTwitter` | String | — | — | Config Twitter. **Nunca referenciado no código.** |
+| `appSecretTwitter` | String | — | — | idem. |
+| `appIdGoogle` | String | — | — | Config OAuth Google. **Sem consumidor vivo de auth.** |
+| `appSecretGoogle` | String | — | — | idem. |
+| `apps` | List\<Application\> | `[]` | — | Aplicações registradas (autenticação Basic / client_credentials). |
+| `roles` | List\<Role\> | `[]` | — | Papéis de jogador (autenticação password). |
+| `websites` | List\<String\> | `[]` | — | Origens para IMPLICIT auth. **Sem consumidor vivo** — só usado no método órfão (2.6). |
+| `runInSilentMode` | boolean | `false` | — | **Persistido, sem consumidor em runtime.** |
+| `baselines` | List\<BaseLine\> | `[]` | — | **Persistido, sem consumidor em runtime.** |
+| `homepage` | String | — | — | Página inicial da gamification no Studio (campo `public`; sem getter; uso pelo frontend). |
+| `ldap` | LDAPConfig | — | — | Config LDAP. **Auth LDAP desabilitada/órfã** (2.6). |
+
+**Diferença schema × runtime:**
+
+- Campos `runInSilentMode`, `baselines`, `websites`, `ldap`, `appId*/appSecret*` (social) e `homepage` são **aceitos no PUT e devolvidos no GET** (round-trip via Jackson). A imprecisão da documentação anterior era dizer que são "removidos silenciosamente" — eles **persistem**; o que falta é **consumidor em runtime** (são inertes para a lógica do servidor).
+- `created_at`/`updated_at` não são preenchidos automaticamente pelo caminho de escrita (`DatabaseRest`), apenas persistidos se vierem no body.
+- `Role` tem `@JsonIgnoreProperties(ignoreUnknown=true)`; `Security` e `Application` **não** têm essa anotação.
+
+### 3.2 `Application` — aplicação registrada (`Application.java`)
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+| --- | --- | --- | --- | --- |
+| `name` | String | — | — | Nome descritivo. |
+| `app_secret` | String | — | sim | Chave secreta (use um GUID, ex.: `/v3/util/guid/new`). |
+| `scope` | String | — | — | Permissões separadas por vírgula. |
+| `whitelist` | List\<String\> | `null` | — | URLs e IPs autorizados (verifica `Referer`/`Origin` e IP remoto). |
+
+**Scopes (constantes literais de `Application.java`):**
+
+| Constante | Valor | Significado |
+| --- | --- | --- |
+| `SCOPE_READ_ALL` | `read_all` | Leitura em todas as coleções. |
+| `SCOPE_WRITE_ALL` | `write_all` | Escrita em todas as coleções. |
+| `SCOPE_DELETE_ALL` | `delete_all` | Exclusão em todas as coleções. |
+| `SCOPE_DATABASE` | `database` | **Obrigatório** para qualquer operação em `/v3/database`. |
+| `SCOPE_READ_CRYPTED` | `read_encrypted_field_values` | Ler campos criptografados. |
+| `SCOPE_READ_PLAYER_PASSWORD` | `read_encrypted_player_password` | Ler senha criptografada do player. |
+| `SCOPE_CROSSDOMAIN` | `cross_domain` | Operações cross-account. |
+| `SCOPE_WRITE_ACTIONLOG` | `write_actionlog` | `POST /v3/action/log` sem `write_all`. |
+| `SCOPE_WRITE_UPLOAD` | `write_upload` | Upload sem `write_all`. |
+
+> `write_own_actionlog` aparece **comentado** no código (`//public static final String SCOPE_WRITE_OWN_ACTIONLOG`) — não existe. Scopes hierárquicos (`{m}_{entidade}_all`) são suportados pela avaliação da seção 2.3 (até 2 níveis de fallback).
+
+### 3.3 `Role` — papel de jogador (`Role.java`, `@JsonIgnoreProperties(ignoreUnknown=true)`)
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+| --- | --- | --- | --- | --- |
+| `name` | String | — | — | Identificador (ex.: `public`, `player`, `admin`). |
+| `timeout` | String | — | — | Validade do token (ex.: `7d`, `1h`, `30m`). Omitir → `+7d`. **Nunca `""`** (gera erro em `DateUtil.fromKeyword("+")`). |
+| `scope` | String | — | — | Permissões separadas por vírgula. |
+| `whitelist` | List\<String\> | `null` | — | URLs/IPs. `null` em alguma role no merge → irrestrito (2.5). |
+
+Roles com semântica especial no código:
+
+- **`public`** — usada pelo `SecurityFilter`/`AuthBean` quando o Basic traz só `apiKey` (sem secret). Se não existir, `scope` fica `null` → **nenhuma verificação de scope** é feita (passa em tudo nessa camada).
+- **`player`** — fallback de `findRoleCalculatedToPlayer` quando o principal não tem roles.
+
+### 3.4 `BaseLine` — janela temporal (`BaseLine.java`)
+
+| Campo | Tipo | Descrição |
+| --- | --- | --- |
+| `start` | Date | Início. |
+| `end` | Date | Fim. |
+
+Campos package-private, sem getters, **sem consumidor em runtime**.
+
+### 3.5 `LDAPConfig` — configuração LDAP (`auth/ldap/LDAPConfig.java`)
+
+| Campo | Tipo | Descrição |
+| --- | --- | --- |
+| `active` | boolean | Ativar LDAP. |
+| `host` | String | Host do servidor. |
+| `port` | String | Porta (ex.: `389`). |
+| `dc` | String | Domain Component. |
+| `ou` | String | Organizational Unit. |
+
+**LDAP está desabilitado/órfão.** O bloco que usaria `LDAPConfig.isActive()` está comentado dentro do método `authenticate()` órfão. Definir `ldap.active=true` não tem efeito em nenhum fluxo acessível.
+
+### 3.6 Coleções relacionadas (separadas de `security`)
+
+Configuradas/usadas no domínio de autenticação, mas em **coleções próprias** (registradas em `Entity`):
+
+- **`auth_module`** (`AuthModule`) — módulos de autenticação **customizados em Groovy** (PAM stacking). Campos: `_id`, `name`, `script`, `relevance` (`required`/`requisite`/`sufficient`/`optional`), `order` (int), `created`, `updated`, `timeout` (Long, s). Gerenciados por `/v3/auth/module`. Consumidos por `/v3/auth/token` (grant `password`). Observação: a relevância `optional` é declarada mas **ignorada** em `authenticateModules` (só `required`/`requisite`/`sufficient` têm efeito).
+- **`sso_saml`** (`SsoSaml`) — configuração SSO SAML 2.0 (SP/IdP, certificados, flags de assinatura). Endpoint público `/v3/sso/saml`.
+- **`two_factor`** (`TwoFactor`) — configuração de 2FA.
+
+---
+
+## 4. Endpoints
+
+> Toda a gestão de `security` usa o `DatabaseRest` genérico (`@Path("v3/database")`). Requer **scope contendo `database`** (verificado dentro do `DatabaseRest`) **e** aprovação prévia do `SecurityFilter` (tipicamente `read_all`/`write_all`/`delete_all`).
+
+### `GET /v3/database/security/{_id}`
+
+| Aspecto | Detalhe |
+| --- | --- |
+| Finalidade | Ler o documento `security` por `_id`. |
+| Implementação | `DatabaseRest.find()` |
+| Autenticação | Bearer/Studio com scope `database` (+ `read_all`). |
+| Pré-condições | `collection.length > 3`, `id.length > 0`. |
+
+**Query params:**
+
+| Param | Tipo | Descrição |
+| --- | --- | --- |
+| `strict` | boolean | `true` → saída em BSON strict mode. |
+
+**Comportamento real:** `c.findOne("{_id:#}", id).as(HashMap.class)`. Se não autorizado/parâmetros inválidos → retorna `null` com `200 OK`. `{_id}` igual a `me` resolve para o player do token.
 
-## Token Basic da Gamificação (público)
-Para acesso público sem App (signup, leitura):
 ```
-Basic base64(API_KEY + ":")
+GET /v3/database/security/540f14b00ffeeb8c2fe11767?strict=true
+Authorization: Bearer <token com scope database,read_all>
 ```
-Nota: dois-pontos no final, sem app_secret. Usa a role `public` se existir.
 
-## Auth Token (`/v3/auth/token`)
+### `GET /v3/database/security?q={...}`
+
+`DatabaseRest.findAll()` — agregação `{$match: {...}}`, paginada (`Range`, `max_results` default 100, `strict`). Útil para inspecionar/contar documentos `security` (detectar duplicatas).
+
+### `PUT /v3/database/security`
+
+| Aspecto | Detalhe |
+| --- | --- |
+| Finalidade | Criar/atualizar o documento `security`. |
+| Implementação | `DatabaseRest.update()` → `jongo.save(o)` |
+| Full replace ou patch | **Replace do documento inteiro pelo `_id`** (campos omitidos somem). **NÃO** apaga outros documentos. |
+| Side effects | Dispara triggers `BEFORE/AFTER_UPDATE` na coleção `security` + registro no Audit. |
+
+> Se o body **não** tiver `_id`, o servidor gera um `Guid.newShortGuid()` → cria documento `security` avulso. Sempre envie `_id`.
 
-### Request (JSON body)
 ```json
+PUT /v3/database/security
+Authorization: Bearer <token com scope database,write_all>
+Content-Type: application/json
+
 {
-  "grant_type": "password",
-  "apiKey": "API_KEY",
-  "username": "player_email",
-  "password": "plain_text_password"
+  "_id": "540f14b00ffeeb8c2fe11767",
+  "requirePassword": true,
+  "createPlayerIfDontExist": true,
+  "timeZone": "America/Sao_Paulo",
+  "apps": [
+    { "name": "Backend App", "app_secret": "69ab3566607db81962b9686e", "scope": "read_all,write_all,delete_all,database" }
+  ],
+  "roles": [
+    { "name": "public", "scope": "read_all", "timeout": "7d" },
+    { "name": "player", "scope": "read_all,write_actionlog,write_upload", "timeout": "30d" }
+  ]
 }
 ```
 
-**⚠️ Campos obrigatórios:**
-- `grant_type` — DEVE ser `"password"` (sem isso, retorna `invalid_grant`)
-- `username` — NÃO `login` (campo frontend pode usar `login` mas API espera `username`)
-- A senha do Player no banco DEVE ser BCrypt hash (`$2a$...`). Senha em texto plano causa `"Invalid salt version"`
+### `POST /v3/database/security`
+
+`DatabaseRest.insert()` — `insert(o)` (não upsert). Gera `_id` se ausente. Dispara triggers `BEFORE/AFTER_CREATE` + Audit. Em coleção singleton, prefira `PUT`.
+
+### `DELETE /v3/database/security?q={...}`
+
+`DatabaseRest.delete()` — exige `q.length >= 3`. Coleta `_id`s afetados (se total ≤ 20.000), dispara triggers `BEFORE/AFTER_DELETE` + Audit, e remove por `{q}`. Apagar o documento `security` deixa `find()` retornando `new Security()` (defaults).
+
+### `POST /v3/auth/token`
+
+| Aspecto | Detalhe |
+| --- | --- |
+| Finalidade | Emitir access_token Bearer. |
+| Autenticação | Pública (path liberado no `SecurityFilter`). |
+| Content-Type | `application/x-www-form-urlencoded` **ou** `application/json`. |
+
+Grant types e expirações: ver seção 2.4. Exemplo `client_credentials` (form):
+
+```
+POST /v3/auth/token
+Content-Type: application/x-www-form-urlencoded
+
+client_id=<apiKey>&client_secret=<app_secret>&grant_type=client_credentials
+```
+
+Resposta:
 
-### Response
 ```json
 {
-  "access_token": "eyJ...",
+  "access_token": "eyJhbGciOiJIUzUxMiIsImNhbGciOiJHWklQIn0...",
+  "refresh_token": "eyJhbGciOiJIUzUxMiIs...",
   "token_type": "Bearer",
-  "expires_in": "1772..."
+  "expires_in": "1747862400000"
 }
 ```
 
-### Campos da Security que afetam auth
-| Campo | Tipo | Descrição |
-|-------|------|-----------|
-| `requirePassword` | boolean | Se `true`, valida senha BCrypt. **NÃO** é `passwordRequired` |
-| `createPlayerIfDontExist` | boolean | Se `true`, cria player automaticamente no login. **NÃO** é `autoCreatePlayer` |
+`expires_in` = timestamp Unix **em milissegundos**.
+
+### `/v3/auth/module` (módulos Groovy)
+
+| Método | Caminho | Função |
+| --- | --- | --- |
+| `GET` | `/v3/auth/module/{id}` | Buscar módulo por id. |
+| `GET` | `/v3/auth/module` | Listar/filtrar (`q`, `published_min/max`, `orderby`, `reverse`, `max_results`). |
+| `POST` | `/v3/auth/module` | Criar/atualizar — **compila** o script antes; se falhar retorna `status: ERROR`. |
+| `DELETE` | `/v3/auth/module/{id}` | Excluir. |
+
+---
+
+## 5. Regras de Negócio
+
+Regras que **estão no código mas não no schema**:
+
+- **Scope `database` + `*_all` (camada dupla).** `/v3/database/*` precisa passar pelo `SecurityFilter` (`read_all`/`write_all`/`delete_all` ou hierárquicos) **e** pelo `DatabaseRest` (`scope` contém `database`). Token sem `database` recebe resposta vazia/`200` no `DatabaseRest`; sem `*_all` recebe `401` no filtro.
+- **Basic público sem role `public`.** Se a role `public` não existir, `scope` fica `null` → o `SecurityFilter` **não** verifica scope → passa em todos os endpoints daquela camada.
+- **`requirePassword` (com nuance).** Em `authenticatePassword(player, password)`: erro de senha só ocorre se `password != null && requirePassword && (user.password == null || !BCrypt.checkpw(password, user.password))`. Logo:
+  - `requirePassword=false` → senha ignorada (qualquer login passa).
+  - `requirePassword=true` **mas `password` ausente/null** no request → a condição curto-circuita e **passa sem checar senha**.
+  - `requirePassword=true` com senha em texto plano (não-BCrypt) → `BCrypt.checkpw` falha → "password incorrect for player".
+- **`createPlayerIfDontExist` (caminho vivo = `createIfDontExist`).** Usado na **ingestão de action logs** (`ActionManager`/`ActionRest`) e em `PlayerRest`/`InGrupo`. Se `true` e o player não existe: verifica `Account.players_allowed`; se o limite foi atingido, **loga no console e NÃO cria** (sem exceção); senão cria o `Player`. (No `authenticatePassword`, o mesmo limite **lança** exceção.)
+- **`isAppAllowed` exige `count == 1`.** `db.security.count({"apps.app_secret": <secret>}) == 1`. Se `0` → falso; se `≥ 2` (secret duplicado entre apps/documentos) → **também falso**. Combine com o risco de documentos `security` duplicados.
+- **Reuso de token (player).** Antes de emitir, o fluxo busca uma `authentication` válida do player (`expires_in >= now`); se existir, **reusa** o mesmo access_token.
+- **Singleton só por convenção.** `find()` faz `findOne()` sem filtro. Vários documentos `security` → resultado não determinístico.
+- **`find()` nunca retorna null** → consumidores sempre recebem ao menos `new Security()` (defaults).
+- **Triggers e Audit em escrita de `security`.** PUT/POST/DELETE em `security` disparam Triggers (Groovy) e gravam Audit como qualquer coleção. Surpreendente para um documento de configuração — uma trigger mal escrita em `security` afeta a configuração de segurança.
+
+---
+
+## 6. Comportamentos Automáticos
+
+| Comportamento | Trigger | Impacto | Persistência |
+| --- | --- | --- | --- |
+| `_id` automático | PUT/POST em `security` sem `_id` | Cria documento com `Guid.newShortGuid()` | Sim (documento avulso) |
+| Triggers `BEFORE/AFTER_CREATE/UPDATE/DELETE` | Qualquer escrita em `security` via `DatabaseRest` | Executa scripts Groovy registrados na coleção `security` | Depende da trigger |
+| Audit log | Qualquer escrita em `security` | Registro em Audit (`EVENT_CREATE/UPDATE/DELETE`) | Sim |
+| Criação automática de player | `createIfDontExist` (ingestão de action log, operações de player) com `createPlayerIfDontExist=true` | Cria `Player` se não existir e dentro de `players_allowed` | Sim |
+| Reuso de access_token | `/v3/auth/token` (password) com sessão válida | Devolve token existente em vez de novo | Não (já existia) |
+| `read_all`/limite diário | Cada request via `StatisticManager.newApiRequest` | Conta requisições; estoura limite → `401` | Em memória/estatística |
+| Índice `apps.app_secret` | `ConnectionPool.createIndexes()` na inicialização | `createIndex({apps.app_secret: 1})` na coleção `security` | Sim (índice Mongo) |
+
+#### Efeitos colaterais de uma escrita em `security`
+
+```mermaid
+flowchart LR
+    A[PUT/POST /v3/database/security] --> B{tem _id?}
+    B -- nao --> C[gera shortGuid]
+    B -- sim --> D[Trigger BEFORE_*]
+    C --> D
+    D --> E[jongo.save / insert]
+    E --> F[Trigger AFTER_*]
+    F --> G[Audit.log]
+```
+
+---
+
+## 7. Suportado vs NÃO Suportado
+
+### ✅ Suportado (caminho vivo no código)
+
+- Autorização por `SecurityFilter` em toda req `/v3/**` (Basic, Account, Studio, Bearer).
+- Basic com `app_secret` (validação `isAppAllowed`, `count == 1`).
+- Basic público (`apiKey:` sem secret) → role `public`.
+- Bearer JWT (HS512 + GZIP) com claims `apiKey`, `appSecret`, `player`, `scope`, `account`, `user`, `whitelist`.
+- Studio token (lib auth0 `JWTVerifier`) e Account token.
+- `/v3/auth/token`: `client_credentials`, `password`, `refresh_token`.
+- Scope hierárquico (`{m}_{path}_all`, até 2 níveis de fallback) + exceções `write_actionlog`/`/v3/mobile/device`.
+- Whitelist por IP/URL (App e Role) via `startsWith`.
+- Merge de múltiplas roles e role individual por id de player.
+- `requirePassword` (BCrypt) e `createPlayerIfDontExist` (via `createIfDontExist`).
+- `timeZone` (challenges/bônus/conquistas) e `inlineEditable` (edição inline).
+- Módulos de autenticação customizados Groovy (`/v3/auth/module`, PAM stacking) — relevâncias `required`/`requisite`/`sufficient`.
+- Índice MongoDB em `apps.app_secret` criado na inicialização.
+- SSO SAML (`/v3/sso/saml`, coleção `sso_saml`) e 2FA (coleção `two_factor`) — features próprias.
+
+### ❌ NÃO Suportado / inerte / órfão
+
+- **`AuthenticationManager.authenticate(auth_mode, …)` (9 args)** — não chamado por nenhum endpoint. Logo, **estão órfãos**:
+  - **Auth LDAP** — bloco comentado **e** método órfão; `LDAPConfig.active=true` sem efeito.
+  - **Auth Facebook/Google** — `AuthenticationFacebook`/`AuthenticationGoogle` instanciados só no método órfão; o ramo de auth tem `// TODO`.
+  - **Validação de `websites` (IMPLICIT)** — `isWebsiteAllowed` só é chamado dentro do método órfão; **não há caminho vivo** que valide `websites`.
+  - **Default de expiração de 30 dias** — existe só no método órfão.
+- **Twitter** — `appIdTwitter`/`appSecretTwitter` nunca referenciados em lugar nenhum.
+- **`runInSilentMode`, `baselines`** — persistidos e devolvidos, **sem consumidor em runtime**.
+- **`homepage`** — persistido (uso pelo frontend Studio); sem consumidor server-side de auth.
+- **`SecurityRest` dedicado** — não existe; gestão via `DatabaseRest`.
+- **Full-replace de coleção** — `SecurityDaoMongo.update()`/`SecurityManager.update()` (remove+save) são **código morto no caminho Java** (escrita real = `save()` por `_id`). Só seriam executados se um script Groovy os chamasse explicitamente (ver 2.1).
+- **PATCH/merge parcial** — PUT substitui o documento inteiro pelo `_id` (não faz merge).
+- **Unicidade do documento** — não imposta pelo código.
+- **Rotação/revogação de token** — JWT não é rastreado no banco; sem blacklist; expira só por prazo.
+- **`expires_in` em segundos (OAuth2)** — retorna timestamp Unix em milissegundos.
+- **Relevância `optional` de auth module** — declarada mas ignorada em `authenticateModules`.
+
+---
+
+## 8. Segurança e Permissões
+
+- **Isolamento por gamificação:** cada gamificação tem seu próprio banco; a coleção `security` é escopada via `manager.getJongoConnection()` (por apiKey).
+- **Chave JWT hardcoded e global:** `TokenUtil.SECRET_KEY = "d61de14ad05f48c5283bad0f5924071d87766219"` — fixa, HS512 + GZIP, **compartilhada por todas as gamificações**. A separação entre gamificações depende da validação do claim `apiKey` contra o endpoint no `SecurityFilter`, não da chave de assinatura. Studio usa a mesma chave via auth0 `JWTVerifier`.
+- **Refresh token de 1 ano** sem acesso (`generateRefreshToken`), reidratável em access tokens — janela longa de re-emissão.
+- **Whitelist por `startsWith`, sem CIDR/wildcard:** `isRequestWhiteListed` testa `url.startsWith(ref) || ip.startsWith(ref)`. IP é lido de `X-Forwarded-For`, `Proxy-Client-IP`, `WL-Proxy-Client-IP`, `HTTP_CLIENT_IP`, `HTTP_X_FORWARDED_FOR`, `RemoteAddr` (nessa ordem), **sem sanitização** — spoofável e sujeito a match parcial (ex.: `"10.0.0."` casa `10.0.0.7` e `10.0.0.99`). Se não houver `Referer`/`Origin` e a whitelist estiver setada, `url` é `null` → `NPE` → vira `401`.
+- **Scope sem sanitização forte:** `scope.replaceAll(" ", "")` remove espaços e compara via `indexOf`/`contains`. Scope malformado pode gerar falso negativo (negar acesso), não falso positivo.
+- **Senha do player:** só validada se `requirePassword=true`. Default `false` → qualquer senha aceita. Mesmo com `true`, request sem `password` passa (seção 5).
+- **Triggers em `security`:** escritas disparam Groovy — superfície para lógica não-intencional sobre a própria config de segurança.
+- **`/v3/auth/token` público:** força bruta de `client_secret`/senha não é bloqueada pela camada de filtro (só pelo limite diário de API agregado por gamificação).
+
+---
+
+## 9. Observabilidade e Troubleshooting
+
+### Verificar a configuração atual
+
+```
+GET /v3/database/security/<apiKey>?strict=true
+Authorization: Bearer <token com scope database,read_all>
+```
+
+### Detectar documentos `security` duplicados (causa de comportamento errático)
+
+```
+GET /v3/database/security/count            # via DatabaseRest /count?collection=security
+# ou
+POST /v3/database/security/aggregate
+[ { "$group": { "_id": null, "total": { "$sum": 1 } } } ]
+```
+
+Espera-se `total = 1`. `≥ 2` explica `isAppAllowed` falhando (exige `count == 1`) e `find()` não determinístico.
+
+### Verificar app_secret cadastrado
+
+```
+GET /v3/database/security/<apiKey>?strict=true
+```
+
+Inspecione `apps[].app_secret`. Lembre: `isAppAllowed` exige **exatamente um** documento com aquele secret.
+
+### Testar emissão de token
+
+```
+POST /v3/auth/token
+Content-Type: application/x-www-form-urlencoded
+
+client_id=<apiKey>&client_secret=<app_secret>&grant_type=client_credentials
+```
+
+### Auditoria de mudanças em `security`
+
+Escritas geram Audit (`EVENT_CREATE/UPDATE/DELETE`) — consulte a coleção de auditoria para "quem mudou a security e quando".
+
+### Erros comuns
+
+| Erro | Causa provável |
+| --- | --- |
+| `api_key or app_secret is not valid or app_secret is not enabled in Funifier Studio.` | Basic com secret não cadastrado em `apps`, ou secret duplicado (`count != 1`). |
+| `Need to inform a type of authentication. E.g. Basic, Studio or Bearer.` | Header `Authorization` ausente/prefixo desconhecido. |
+| `Authorization token bearer is not valid.` | Bearer expirado/malformado/assinado com chave errada (sem `apiKey` e sem `account`). |
+| `Studio token is invalid.` | Studio token inválido (`getValueStudio` retornou null). |
+| `Domain or IP is not authorized. Ask the admin to add this in the gamification whitelist.` | App/Role com `whitelist` e origem/IP fora dela (ou ausência de `Referer`/`Origin`). |
+| `You have exceeded your gamification daily api requests limits` | Limite diário da Account atingido. |
+| `You dont have permission to {m} in {entity} endpoint, you need {m}_{entity_full} or {m}_all access to do it` | Scope sem `*_all`/`*_{path}` adequado. |
+| Resposta vazia (`null`/`200`) em `/v3/database/security` | Scope sem `database`, ou `collection.length <= 3`/`id` ausente. |
+| `auth_module_failed` | Auth module Groovy retornou status 2 (falha) com output. |
+| `password incorrect for player` | `requirePassword=true` e BCrypt não confere (ou senha não-BCrypt). |
+| NPE/erro ao gerar token de player | `role.timeout = ""` (use `null`/omita), ou role resolvida `null` no overload com whitelist. |
+
+---
+
+## 10. Exemplos Práticos
+
+### Exemplo mínimo — um app de servidor + role player
 
-### ⚠️ Role timeout NUNCA string vazia
 ```json
-// ❌ ERRADO — causa NPE no auth (DateUtil.fromKeyword("+") falha)
-{ "name": "player", "scope": "...", "timeout": "" }
+PUT /v3/database/security
+Authorization: Bearer <token com scope database,write_all>
+Content-Type: application/json
 
-// ✅ CORRETO — omitir campo para timeout padrão (7 dias)
-{ "name": "player", "scope": "..." }
+{
+  "_id": "540f14b00ffeeb8c2fe11767",
+  "createPlayerIfDontExist": true,
+  "requirePassword": false,
+  "apps": [
+    { "name": "Server App", "app_secret": "a1b2c3d4e5f6a7b8c9d0e1f2", "scope": "read_all,write_all,delete_all,database" }
+  ],
+  "roles": [
+    { "name": "player", "scope": "read_all,write_actionlog,write_upload", "timeout": "7d" }
+  ]
+}
+```
 
-// ✅ CORRETO — valor explícito
-{ "name": "player", "scope": "...", "timeout": "7d" }
+### Exemplo avançado — roles + whitelist + timezone + senha obrigatória
+
+```json
+{
+  "_id": "540f14b00ffeeb8c2fe11767",
+  "createPlayerIfDontExist": true,
+  "requirePassword": true,
+  "timeZone": "America/Sao_Paulo",
+  "inlineEditable": false,
+  "apps": [
+    {
+      "name": "Backend Server",
+      "app_secret": "a1b2c3d4e5f6a7b8c9d0e1f2",
+      "scope": "read_all,write_all,delete_all,database",
+      "whitelist": ["10.0.0.", "192.168.1."]
+    },
+    {
+      "name": "Frontend Read Only",
+      "app_secret": "f9e8d7c6b5a4f3e2d1c0b9a8",
+      "scope": "read_all,write_actionlog",
+      "whitelist": ["https://app.empresa.com"]
+    }
+  ],
+  "roles": [
+    { "name": "public", "scope": "read_all", "timeout": "1d" },
+    { "name": "player", "scope": "read_all,write_actionlog,write_upload", "timeout": "30d" },
+    { "name": "admin",  "scope": "read_all,write_all,delete_all,database", "timeout": "8h" }
+  ]
+}
+```
+
+> A `whitelist` usa `startsWith` (sem CIDR). `"10.0.0."` cobre toda a faixa `10.0.0.x` por prefixo de string — confirme que isso é o pretendido.
+
+### Anti-pattern — o que NÃO fazer
+
+```json
+{
+  "roles": [
+    { "name": "player", "scope": "read_all,write_all", "timeout": "" }
+  ]
+}
 ```
 
-## Validações e Testes
-- [ ] Role `public` criada com scope `read_all`
-- [ ] Role `player` criada com scope incluindo `database`
-- [ ] App criada com secret gerado
-- [ ] Token Basic do App acessa `/v3/database/collections`
-- [ ] Token Basic público (sem app) acessa endpoints de leitura
+Problemas:
+
+1. **Sem `_id`** → o servidor gera um `Guid.newShortGuid()` e cria um **segundo** documento `security`. Como `find()` faz `findOne()` sem filtro, ele pode passar a "vencer" sobre o real, e `isAppAllowed` (que exige `count == 1`) pode quebrar.
+2. **`timeout: ""`** → `DateUtil.fromKeyword("+")` → erro/NPE na emissão do token do player.
+3. **PUT sem `apps`** (omitindo) → como o PUT substitui o documento inteiro pelo `_id`, **todos os apps somem** daquele documento. Sempre reenvie o documento completo.
+4. **Sem scope `database` em nenhum app/role** → `/v3/database` retorna vazio.
+
+---
+
+## Checklist de Configuração
+
+- [ ] `_id` preenchido com a API Key da gamificação (nunca deixar o servidor gerar).
+- [ ] Exatamente **um** documento na coleção `security` (cheque com `aggregate $group/count`).
+- [ ] Pelo menos um `app` com `app_secret` único (GUID) — secret duplicado quebra `isAppAllowed` (`count == 1`).
+- [ ] Scope dos apps inclui `database` **e** `read_all`/`write_all`/`delete_all` para usar `/v3/database`.
+- [ ] Role `player` com `timeout` não-vazio e diferente de `""` (use `null`/omita ou `7d`).
+- [ ] Role `public` definida se acesso Basic público for necessário (senão Basic público passa sem scope).
+- [ ] `timeZone` preenchido se challenges/bônus por hora/dia forem usados.
+- [ ] `requirePassword` consciente: `false` (default) = sem validação de senha; `true` ainda passa se o request não enviar `password`.
+- [ ] PUT sempre com o documento completo (campos omitidos são apagados daquele `_id`).
+- [ ] `whitelist` com prefixos corretos (lembre: `startsWith`, sem CIDR/wildcard).
+- [ ] Não confiar em LDAP/Facebook/Google/Twitter/`websites`/`baselines`/`runInSilentMode` — inertes ou órfãos no código atual.
+- [ ] Triggers cadastradas na coleção `security` revisadas (escritas disparam Groovy + Audit).