funifier-mcp 0.3.17 → 0.3.18

package/datasource-funifier-docs/.skills-map.json

@@ -137,5 +137,9 @@
   ],
   "funifier-manage-indexes": [
     "knowledge/modules/database.md"
+  ],
+  "funifier-audit-permissions": [
+    "knowledge/guides/permission-audit.md",
+    "knowledge/modules/security.md"
   ]
 }

package/datasource-funifier-docs/.validation.json

@@ -1,13 +1,49 @@
 {
-  "generatedAt": "2026-06-12T12:18:00Z",
+  "generatedAt": "2026-06-12T16:08:00Z",
   "skills": {
+    "funifier-audit-permissions": {
+      "configHash": "f0569bdb0e11e1a2c6a11f6a4ff9cfd940668c7431bee06342b29faab32510fc",
+      "status": "verified",
+      "claims": [
+        {
+          "claim": "SecurityFilter.doFilter evaluates (method, path) by computing verb (GET→read, POST/PUT→write, DELETE→delete) and entity_full (path after /v3/ with slash→underscore), then matching scope tokens in order: {verb}_all, exact {verb}_{entity_full}, fallback {verb}_{prefix}_all minus-1 and minus-2 trailing segments",
+          "gitnexusQuery": "SecurityFilter",
+          "critical": true,
+          "status": "verified",
+          "evidence": {
+            "symbol": "Class:src/main/java/com/funifier/rest/v3/filter/SecurityFilter.java:SecurityFilter",
+            "file": "src/main/java/com/funifier/rest/v3/filter/SecurityFilter.java"
+          }
+        },
+        {
+          "claim": "DatabaseRest requires the literal 'database' scope keyword on ALL /v3/database handlers including GET operations — grammar tokens such as read_all alone are insufficient; this is enforced within SecurityFilter.doFilter before requests reach DatabaseRest handlers",
+          "gitnexusQuery": "doFilter",
+          "critical": true,
+          "status": "verified",
+          "evidence": {
+            "symbol": "Method:src/main/java/com/funifier/rest/v3/filter/SecurityFilter.java:SecurityFilter.doFilter#3",
+            "file": "src/main/java/com/funifier/rest/v3/filter/SecurityFilter.java"
+          }
+        },
+        {
+          "claim": "Bearer tokens embed the player's role scope string at login time; role scope changes only affect sessions created after the change — existing live Bearer tokens carry the scope at their issuance time",
+          "gitnexusQuery": "SecurityFilter",
+          "critical": true,
+          "status": "verified",
+          "evidence": {
+            "symbol": "Class:src/main/java/com/funifier/rest/v3/filter/SecurityFilter.java:SecurityFilter",
+            "file": "src/main/java/com/funifier/rest/v3/filter/SecurityFilter.java"
+          }
+        }
+      ]
+    },
     "funifier-configure-security": {
-      "configHash": "fba0f846a53838e369f5c079104cd4a2f16a9d535a0320701d16287e53f35496",
+      "configHash": "a05c3dc778b494d2d9d781787dd2231c1ae5720c3e368b41071f02df85a1a922",
       "status": "verified",
       "claims": []
     },
     "funifier-create-action": {
-      "configHash": "2b0f8eddb8f942fc407c1d19b15fdc80cb7d9a1e01c1093befdfd3c483c1cb68",
+      "configHash": "378dcd46c1dbad66e0363790d65d5bc0bba9ea3b294a97b571cc6d87c26ddf11",
       "status": "verified",
       "claims": [
         {
@@ -33,7 +69,7 @@
       ]
     },
     "funifier-create-aggregate": {
-      "configHash": "9598173385df039c369c8efc036ec22faaa3f9e56cb6c787498bf3d72b18a634",
+      "configHash": "1c241176306556b5f4e626f49bb2961fa060678b83f0f9ef72d862249f3e6918",
       "status": "verified",
       "claims": [
         {
@@ -49,7 +85,7 @@
       ]
     },
     "funifier-create-audit": {
-      "configHash": "17d53b67ecf952aaa352f0799e465d00de59960cd51cea31dee6f5d9ad5f5c8f",
+      "configHash": "0ca754be3545a16a6efb50ca2c4b360f1438efa1cd1bc2b5109aa76768376e07",
       "status": "verified",
       "claims": [
         {
@@ -85,7 +121,7 @@
       ]
     },
     "funifier-create-challenge": {
-      "configHash": "45e50eab442325d3342dddff5d7c48f34002fe0182ed78c31a48fffdb8eafd03",
+      "configHash": "7065294da9c53a9d1bbe544749ff552d6674d0d77e2534ea17e43fae4c72474c",
       "status": "verified",
       "claims": [
         {
@@ -111,7 +147,7 @@
       ]
     },
     "funifier-create-competition": {
-      "configHash": "ed7fe6dc128ebe0cbb417544d2f25209cf472a11fd38e4b78bb33b7662e54618",
+      "configHash": "0de8bcda95d0a1764ef4ce7aa7e78c53c7f7d492012534ecaf7f87600c42f078",
       "status": "verified",
       "claims": [
         {
@@ -137,7 +173,7 @@
       ]
     },
     "funifier-create-crossword": {
-      "configHash": "c1e731de20525b88b05c1f644c196fa5aa31c593a75f7f03de8c8030564ab5fb",
+      "configHash": "63ebc6f1e0589aaa748464e54b3dc3460094fa41764922534b6017288fc79541",
       "status": "verified",
       "claims": [
         {
@@ -153,7 +189,7 @@
       ]
     },
     "funifier-create-custom-object": {
-      "configHash": "58677f7f00c4d432e792f825bbc12b11e61722057c143d4a291da600d5beb758",
+      "configHash": "8aa7a96fdc72793c3d095db04831396d58a1aca931a7542cc8d5b8eed2e0c31d",
       "status": "verified",
       "claims": [
         {
@@ -169,7 +205,7 @@
       ]
     },
     "funifier-create-custom-page": {
-      "configHash": "d7a517d522858c659e5ead012c9f0594829aee22d96cda561536fbb803cd5db0",
+      "configHash": "7eac6647589aee0ca03e2fc213dac98a212ef0100e2f69da38cb758f7f65a7e7",
       "status": "verified",
       "claims": [
         {
@@ -185,7 +221,7 @@
       ]
     },
     "funifier-create-folder": {
-      "configHash": "ec7b1e3fadcd07d89f271f1bc10a28f820916fe8c0e645da88d48a43db868966",
+      "configHash": "16b0c0ae4ddebd51a16a0f330a80bed8c186cd7a760a9e52a5fb16d3cf6e462f",
       "status": "verified",
       "claims": [
         {
@@ -211,7 +247,7 @@
       ]
     },
     "funifier-create-lastmile": {
-      "configHash": "176113c689332843b24d22f7705d1361dfabf3e369de816b59b33a86ed0d9041",
+      "configHash": "e769c3ad773a9069ae41902d52195b81cfaaf6eb61cc15fb1d443c95ae512e55",
       "status": "verified",
       "claims": [
         {
@@ -227,7 +263,7 @@
       ]
     },
     "funifier-create-leaderboard": {
-      "configHash": "1cd6bca4e73fda88a8a4e965af46f45acbba2508098557f321819fbe04d57fb3",
+      "configHash": "f0baaf27834eb5f75c75ba1ddb0054e72a1cf88a52d685601acd4781fafec025",
       "status": "verified",
       "claims": [
         {
@@ -243,7 +279,7 @@
       ]
     },
     "funifier-create-level": {
-      "configHash": "c50ed12fceedfc2288bd2006f743528f440ab57de9f8321ae0297f0eb6199eae",
+      "configHash": "807c32381d542e5e1bbd678b29bc79751af340b7e00a31264a1dd24839306dab",
       "status": "verified",
       "claims": [
         {
@@ -269,7 +305,7 @@
       ]
     },
     "funifier-create-lottery": {
-      "configHash": "073bed793dd691ac19d095fa52839f4129532b7ff49eef4e35e9c84954d1b540",
+      "configHash": "ba9945f649f2e2fe91d545d27131b0e705b729deba192d121b8e41a03e3d5078",
       "status": "verified",
       "claims": [
         {
@@ -295,7 +331,7 @@
       ]
     },
     "funifier-create-mystery": {
-      "configHash": "ab423bcca3614806f63a3366db19629fe3127dc2989975f181cb0171be37d312",
+      "configHash": "0251df7c50e9629c592abef26894cc4b37d2a00c32ce6021c47eeedad3df35bb",
       "status": "verified",
       "claims": [
         {
@@ -311,7 +347,7 @@
       ]
     },
     "funifier-create-notification": {
-      "configHash": "1fd4dbbc94ba9aa72ae464b4c2c40b23f612e8b7c49fae7a8f1136950c0474a2",
+      "configHash": "7c3a31fce953b96fd477ddd1f437cc7b617d38b999fec45944a80ab58693306f",
       "status": "verified",
       "claims": [
         {
@@ -327,7 +363,7 @@
       ]
     },
     "funifier-create-point": {
-      "configHash": "68c1da1a809c5ad6a360766d257bdc14fefff7162e4072ab2221e0f13d0be0a1",
+      "configHash": "a5d84d1e85e7fe8b3d6af3acb19122243c75456c101b991491ee510716607c4a",
       "status": "verified",
       "claims": [
         {
@@ -353,7 +389,7 @@
       ]
     },
     "funifier-create-quiz": {
-      "configHash": "ccec76679412c2f2a45b3afd30cc0cf266ed29dc1d71c23c6542638819556c7a",
+      "configHash": "dd932897848f30800c71e17acdaf08699dd1c28f5d5b9de618c696bfa88be5b6",
       "status": "verified",
       "claims": [
         {
@@ -379,7 +415,7 @@
       ]
     },
     "funifier-create-scheduler": {
-      "configHash": "841ffa14cc86b91dd2f1d744bbc55def6bfe6de6baf6380fff435625963fdd7e",
+      "configHash": "9f986517a5c5d8caf315b6ee5ce93150666a7f3a0bf45aefe4f46fa883665e38",
       "status": "verified",
       "claims": [
         {
@@ -395,12 +431,12 @@
       ]
     },
     "funifier-create-story": {
-      "configHash": "df98fbfb6f812c49736fb99ab6d6de2575289ce28e915bc95ec994158e3bc9b5",
+      "configHash": "5c53e20e201766c7b2fe29a253c50655cd7fad0fc82edb3543957c79697996bf",
       "status": "verified",
       "claims": []
     },
     "funifier-create-swap": {
-      "configHash": "ef4c5ca6bb0d66976d97dc8a2516da8f112ae0eb6a4e449d678f151dfed646e8",
+      "configHash": "3067da9da8726b0f0191aac05d711e2870dada98044e9fd442bdb2472654d053",
       "status": "verified",
       "claims": [
         {
@@ -416,7 +452,7 @@
       ]
     },
     "funifier-create-trigger": {
-      "configHash": "44204bb97039cb17d5a1d97757562d9fa16baefd5caf0e1f1a6cc0fa0390db4d",
+      "configHash": "21a46732f80324f9662064e8d96528f26c7cfa277f152905fd537be8ef12dab1",
       "status": "verified",
       "claims": [
         {
@@ -452,7 +488,7 @@
       ]
     },
     "funifier-create-virtual-good": {
-      "configHash": "70415901417a63692f7a1325300d2b57644a067dc55917a9e9b64e92bd3c14af",
+      "configHash": "9a78b550bfdd28271fcb1d225da8a6f0a68112735209765b32c34fe0be981c33",
       "status": "verified",
       "claims": [
         {
@@ -468,7 +504,7 @@
       ]
     },
     "funifier-create-webhook": {
-      "configHash": "e9ff0ebe0b9829bf61011b3abc846806a36f0245e4075a34aecdcb86d837c081",
+      "configHash": "cc84a72a02ade14142576f6f66a806e10b400ce624b42509dd9bcb8777424d70",
       "status": "verified",
       "claims": [
         {
@@ -484,7 +520,7 @@
       ]
     },
     "funifier-create-websocket": {
-      "configHash": "66965c501a68223a84647f0fd2f5bb81fb898318e86e901819a7e9a560201096",
+      "configHash": "0689d726bebbe170d03132e53a943978b78392e2c1240a38b147e3813d3f6322",
       "status": "verified",
       "claims": [
         {
@@ -500,7 +536,7 @@
       ]
     },
     "funifier-create-widget": {
-      "configHash": "ed11b1648c6a67e24aa4e6a35a29864a48fa8968b7c5e83275cde8f2464273f2",
+      "configHash": "d4e6e29b2dadbe4838b1dd1e820989c2fc88c7a63fc41e0b871ec725cf2c3296",
       "status": "verified",
       "claims": [
         {
@@ -516,12 +552,12 @@
       ]
     },
     "funifier-date-handling": {
-      "configHash": "82a41d6369f0a1e2ad5e0a09d7c6c318c970436c7b59a0b42611cd6d5e14575e",
+      "configHash": "07e910af002f3bbf6cee50fedf10acfea9a40162eeee567256076bdf612b02e5",
       "status": "verified",
       "claims": []
     },
     "funifier-debug": {
-      "configHash": "37c75988e8ddf1c5eb9ef0593a83159410d85a744eb1ff262ba02dc4789fa2a4",
+      "configHash": "d464a6ec61f5122298bd6d855a1584be307d358b4253f4854643aeaffff319e9",
       "status": "verified",
       "claims": [
         {
@@ -537,7 +573,7 @@
       ]
     },
     "funifier-help": {
-      "configHash": "7af4ce568c8429bd33b797d070dfaed47ad08618ce1074c8532df0aa33fed1c8",
+      "configHash": "1da15e3fcabe8f807cab51fcfbba47686a1a4c03407b6808f5364c314f963908",
       "status": "verified",
       "claims": [
         {
@@ -553,7 +589,7 @@
       ]
     },
     "funifier-implement-frontend": {
-      "configHash": "cb9700aa8484384f913ef6871ea2a40652c08e394b9e1bfb111706da094c56b5",
+      "configHash": "cab5471ae97ab4413b4798b6256f388457246cf91eb494d3d58c722cb806e2ff",
       "status": "verified",
       "claims": [
         {
@@ -579,17 +615,17 @@
       ]
     },
     "funifier-import-csv": {
-      "configHash": "24ca1b985f50466dd781e3cb1b9a67f152b748d60735b8e8211b305a4c74b261",
+      "configHash": "9467463bbae7c65363df7137243ff034ccc23dba2426f3e05211ac5bde03ed17",
       "status": "verified",
       "claims": []
     },
     "funifier-manage-indexes": {
-      "configHash": "d4097ecfb403b1df6ea5e2adaf6359b2e663d3ed57f944476abbd9d77debbb1c",
+      "configHash": "bebb7f00e3b8a6eff8276b7264a33dfc6c912a58adc96f3fc8406e8cb1675df3",
       "status": "verified",
       "claims": []
     },
     "funifier-manage-player": {
-      "configHash": "77efa151e25e2672fcea590f4a5f6bf2f77745875a297e79351f544cff04b73f",
+      "configHash": "9d4a397fac4cd79d2a6168ef689ecd8dff76a28324f9a3e67492a1db573d127f",
       "status": "verified",
       "claims": [
         {
@@ -615,7 +651,7 @@
       ]
     },
     "funifier-manage-team": {
-      "configHash": "624ed9b06b109a2a07e4a921537df1f31d91125486c8ab26745a913c39ac1876",
+      "configHash": "63c9ead124e4ffbab71fea8d320e12edc9aa48053bd9607c315bdd350fd1e5ac",
       "status": "verified",
       "claims": [
         {
@@ -631,7 +667,7 @@
       ]
     },
     "funifier-upload-file": {
-      "configHash": "93b0c2d388aa465794cedd461006dcc1f93e426001c710cb90cc595d076a5ea1",
+      "configHash": "9c3dcaf7351189c3395ae3ea5ac122d5b470b3e1db0b0fd94384880c0094f19c",
       "status": "verified",
       "claims": []
     }

package/datasource-funifier-docs/knowledge/guides/permission-audit.md

@@ -0,0 +1,229 @@
+# Permission Audit Guide
+
+## 1. Visão Geral
+
+### 1.1 O que é este documento
+
+Este guia descreve como usar o `funifier_permissions action=audit` para verificar deterministicamente se os escopos salvos no documento de segurança cobrem os endpoints que o seu projeto usa — e se há escopos concedidos que nenhum endpoint requer. O motor de auditoria espelha `SecurityFilter.doFilter` de `funifier-service`; o veredicto é reproduzível e unit-testado, não dependente de raciocínio LLM.
+
+### 1.2 Quando consultar
+
+- Antes de alterar escopos: saber o que cada role/app autoriza hoje.
+- Após adicionar endpoints: verificar se o scope cobre as novas chamadas.
+- Quando ocorrem 401 inesperados: mapear exatamente qual token está faltando.
+- Ao auditar mínimo privilégio: identificar tokens excedentes que podem ser removidos.
+
+### 1.3 Quando NÃO consultar
+
+- Para **alterar** escopos — use `save_security_role` / `save_api_app` (ações separadas, requerem confirmação do utilizador).
+- Para **perguntas sobre Studio roles/assignments** (permissões de interface) — o audit cobre só API scopes (documento `security`).
+- Para **verificar backups** — use `verify_backup`.
+
+### 1.4 Índice de decisão
+
+| Problema / Situação | O que fazer | Seção |
+|---|---|---|
+| Saber qual auth context usar para uma chamada | Tabela de autenticação | §2 |
+| Construir o manifest de chamadas do projeto | Formato do manifest + exemplo | §3 |
+| Interpretar `missing` / `excess` / `danger` / `missing-principal` | Tipos de finding | §4 |
+| Entender como o motor avalia `(method, path, scope)` | Gramática de escopo | §5 |
+| Saber o que fazer com os findings | Regra de read-only + remediação | §6 |
+
+### 1.5 Restrições críticas
+
+> ⚠️ **O audit é estritamente read-only.** Nenhuma chamada de escrita é feita; nenhum snapshot é gravado. Findings são candidatos para revisão — nunca são aplicados automaticamente.
+
+> ⚠️ **Bearer tokens embtem o scope no momento do login.** Uma alteração de role só afeta sessões novas. Se você corrigiu o scope mas o jogador ainda recebe 401, peça-lhe que faça login novamente.
+
+> ⚠️ **O manifest cobre um repo de cada vez.** Se a sua aplicação tem múltiplos repositórios a chamar a mesma gamificação, combine as entradas manualmente no manifest.
+
+---
+
+## 2. Tabela de Auth Context
+
+Cada chamada API usa um mecanismo de autenticação diferente. O motor resolve qual scope se aplica com base nesse mecanismo (`SecurityFilter.java:153-211`):
+
+| `auth` no manifest | Mecanismo HTTP | Scope usado |
+|--------------------|----------------|-------------|
+| `"public"` | `Basic base64(API_KEY:)` — sem secret | Scope da role `public` no documento de segurança |
+| `"player"` | `Bearer <player token>` | Scope da role sob a qual o jogador fez login (normalmente `player`) — **embutido no token no momento do login** |
+| `"app:<name>"` | `Basic base64(API_KEY:APP_SECRET)` | Scope da entrada `apps[]` cujo `name` é `<name>` |
+| `"role:<name>"` | Qualquer Bearer com role customizada | Scope da role `<name>` no documento de segurança |
+
+**Heurísticas de classificação por stack:**
+
+- Chamadas sem cabeçalho `Authorization` (ou com API_KEY sem secret) → `"public"`
+- Chamadas com token JWT player (`Authorization: Bearer ...`) → `"player"` (ou o nome da role customizada se o SDK permitir escolher)
+- Chamadas com app_secret embutido em env var / config → `"app:<name>"` (use o `name` do entry em `apps[]`)
+- Chamadas de servidor para servidor com secret fixo → `"app:<name>"`
+
+---
+
+## 3. Formato do Manifest
+
+### 3.1 Schema
+
+```json
+{
+  "version": 1,
+  "entries": [
+    {
+      "method": "GET | POST | PUT | DELETE",
+      "path": "/v3/...",
+      "auth": "<auth context — ver §2>",
+      "evidence": "<file:line ou descrição>",
+      "confidence": "high | low"
+    }
+  ]
+}
+```
+
+- **`version`**: deve ser `1`.
+- **`entries`**: máximo de 500 entradas. Cada entrada representa uma chamada distinta de `(method, path, auth)`.
+- **`method`**: case-insensitive; normalizado para maiúsculas internamente.
+- **`path`**: o prefixo `/v3` é adicionado automaticamente se ausente.
+- **`auth`**: obrigatório. Sem `auth` o motor não sabe qual scope avaliar.
+- **`evidence`**: obrigatório. `"src/api.ts:42"` ou `"chamada descoberta em SDK wrapper"`.
+- **`confidence`**: `"high"` (default) para chamadas confirmadas por código; `"low"` para URLs dinâmicas ou inferidas.
+
+### 3.2 Exemplo
+
+```json
+{
+  "version": 1,
+  "entries": [
+    { "method": "GET",    "path": "/v3/player/me",         "auth": "player",       "evidence": "src/profile.ts:12",    "confidence": "high" },
+    { "method": "POST",   "path": "/v3/action/log",        "auth": "player",       "evidence": "src/events.ts:58",     "confidence": "high" },
+    { "method": "GET",    "path": "/v3/widget/rankings",   "auth": "public",       "evidence": "src/embed.html:1" },
+    { "method": "POST",   "path": "/v3/player",            "auth": "app:backend",  "evidence": "workers/sync.ts:34",   "confidence": "high" },
+    { "method": "GET",    "path": "/v3/database/orders",   "auth": "app:backend",  "evidence": "workers/sync.ts:80",   "confidence": "high" },
+    { "method": "GET",    "path": "/v3/challenge",         "auth": "player",       "evidence": "src/gamification.ts:7" }
+  ]
+}
+```
+
+### 3.3 Chamadas com URL dinâmica ou cliente wrapper
+
+Quando não é possível determinar o path exato estaticamente:
+- Use o prefixo mais específico que conhece (e.g. `/v3/database/orders` em vez de só `/v3/database`).
+- Defina `"confidence": "low"` para sinalizar incerteza.
+- **Nunca omita** uma chamada suspeita — é melhor um finding de baixa confiança do que um 401 não detectado em produção.
+
+---
+
+## 4. Tipos de Finding
+
+| Severity | Significado | Impacto |
+|----------|-------------|---------|
+| `missing` | A chamada seria negada com o scope atual | Quebra funcionalidade — 401 em produção |
+| `excess` | Token concedido mas nenhuma entrada do manifest o requer | Candidato a remoção (mínimo privilégio) |
+| `danger` | Padrão de risco estático (independente do manifest) | Risco de segurança — revisar imediatamente |
+| `manual-review` | Token não-path (`cross_domain`, `write_upload`, etc.) — não verificável por análise de caminhos | Verificar manualmente |
+| `public-no-scope-needed` | Path público — scope não é verificado pelo servidor | Informativo; não entra no cálculo de missing/excess |
+| `missing-principal` | Auth context referenciado no manifest não existe no documento de segurança | Entradas desse auth não foram avaliadas |
+
+### 4.1 Findings de `danger` estáticos
+
+Estes são verificados independentemente do manifest:
+
+- `write_all` / `delete_all` / `database` na role `public` → unauthenticated callers têm acesso privilegiado
+- `read_encrypted_field_values` / `read_encrypted_player_password` na role `public` ou `player` → dados encriptados expostos
+- App com `scope` vazio → nenhuma chamada será autorizada para esse app
+
+### 4.2 Narrowing para tokens broad
+
+Quando `read_all`, `write_all` ou `delete_all` autoriza as suas entradas mas tokens exatos (`read_player`, `write_game`, etc.) cobririam o mesmo uso, o finding inclui `narrowingSuggestion` com os tokens exatos sugeridos. Verifique se há consumidores fora deste manifest antes de remover o token broad.
+
+---
+
+## 5. Gramática de Escopo (SecurityFilter.java)
+
+O motor espelha exatamente `SecurityFilter.doFilter`. Ordem de avaliação para cada `(method, path)`:
+
+### 5.1 Paths públicos (sem scope)
+
+`GET /v3/widget`, `GET /v3/global`, `GET /v3/system/global` e seus sub-paths passam sem verificação de scope (`SecurityFilter.java:108-151`). Entradas que acertam estes paths são classificadas `public-no-scope-needed`.
+
+### 5.2 Contexto de autenticação → scope
+
+O scope avaliado depende do mecanismo de auth (ver §2). Studio/Account tokens não passam pela gramática de scope — estão fora do escopo do audit.
+
+### 5.3 Exceções especiais de POST
+
+Verificadas antes da gramática (`SecurityFilter.java:259-263`):
+
+- `POST /v3/action/log` → autorizado se o scope contiver `write_actionlog` (sem precisar de `write_all` ou `write_action_log`)
+- `POST /v3/mobile/device` → autorizado com qualquer scope não-vazio
+
+### 5.4 Regras gramaticais
+
+Para `(method, path)` não cobertos acima (`SecurityFilter.java:230-253`):
+
+1. **verb** = `GET`→`read`, `POST`/`PUT`→`write`, `DELETE`→`delete`
+2. **entity_full** = path após `/v3/`, com `/` substituído por `_` (e.g. `/v3/database/orders/aggregate` → `database_orders_aggregate`)
+3. Verifica na ordem:
+   - `{verb}_all` → rule `all`
+   - `{verb}_{entity_full}` → rule `exact`
+   - `{verb}_{prefix}_all` (minus-1 trailing segment) → rule `fallback-m1`
+   - `{verb}_{prefix}_all` (minus-2 trailing segments) → rule `fallback-m2`
+   - Se nenhum → denied
+
+> **O motor para em m2.** Não há fallback m3 ou superior, mesmo que o path tenha mais segmentos.
+
+### 5.5 Keyword `database` (DatabaseRest.java)
+
+**Regra crítica:** qualquer path `/v3/database/...` requer o token literal `database` no scope, **além** do token gramatical. Aplica-se a **todos os verbos incluindo GET**. Os 13 handlers de `DatabaseRest.java` verificam este keyword explicitamente.
+
+Exemplo: para autorizar `GET /v3/database/orders`, o scope precisa de `read_database_orders` (ou `read_all`) **E** `database`.
+
+### 5.6 Normalização do scope
+
+Espaços são removidos e tokens são separados por vírgula antes da avaliação. `"read_all, write_all"` equivale a `"read_all,write_all"`.
+
+---
+
+## 6. Read-Only Rule e Remediação
+
+### 6.1 O audit nunca escreve
+
+O `funifier_permissions action=audit` é a única ação deste tool que não requer conexão para findings de `danger` (ainda requer para carregar o documento de segurança). Não faz mutações, não grava snapshots.
+
+### 6.2 Fluxo de remediação
+
+Para cada finding `missing`:
+1. Identifique o token exato sugerido em `requiredTokens`.
+2. Decida se vai adicionar ao scope da role (`save_security_role`) ou do app (`save_api_app`).
+3. Confirme a intenção com o utilizador antes de executar.
+4. O tool escreverá um backup automático antes de qualquer mutação.
+
+Para cada finding `excess`:
+1. Verifique se o token pode ser necessário a consumidores **fora** deste manifest.
+2. Se seguro, remova com `save_security_role` / `save_api_app`.
+3. Após remover, corra o audit novamente para confirmar que não surgiram novos `missing`.
+
+Para findings `danger`:
+1. Avalie o risco: quem está a usar o contexto público/player afetado?
+2. Remova o token perigoso ou restrinja o role conforme necessário.
+3. Para `read_encrypted_*` em `public`: é quase sempre um erro de configuração.
+
+---
+
+## 7. Invocação
+
+```
+funifier_permissions action=audit data=<manifest JSON>
+```
+
+O manifest é passado como string JSON no campo `data`. Exemplo de chamada:
+
+```json
+{
+  "action": "audit",
+  "data": "{\"version\":1,\"entries\":[{\"method\":\"GET\",\"path\":\"/v3/player/me\",\"auth\":\"player\",\"evidence\":\"src/api.ts:10\"}]}"
+}
+```
+
+O resultado inclui:
+- `manifest_entries`: número de entradas avaliadas
+- `findings`: lista de findings com `severity`, `principal`, `rule`, `evidence`, `requiredTokens`, `excessTokens`, `narrowingSuggestion`, `detail`
+- `notes`: notas de completude, Bearer freshness, e instrução de verificação para excess

package/datasource-funifier-docs/knowledge/index.md

@@ -106,6 +106,7 @@ A Funifier funciona como um **backend de aplicações**. Independentemente do ti
 | Java Managers | `guides/java-managers.md` | Referência de managers Java | Métodos disponíveis em cada manager (PlayerManager, ActionManager, etc.) para uso em triggers, schedulers e public endpoints |
 | Java Entities | `guides/java-entities.md` | Referência de entidades Java | Campos e tipos dos objetos (Player, Achievement, ActionLog, etc.) e mapeamento para coleções MongoDB |
 | Java Libraries | `guides/java-libraries.md` | Bibliotecas e utilitários Java | JsonUtil, Guid, DateUtil, Unirest, EmailBuilder, Jongo — métodos e exemplos de uso |
+| Permission Audit | `guides/permission-audit.md` | Auditoria de permissões de API | Cross-check código↔Funifier: manifest de chamadas → missing scopes, excess tokens, danger findings; gramática de scope (SecurityFilter), keyword `database`, auth context, remediação |
 
 ---