funifier-mcp 0.3.16 → 0.3.18

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

@@ -0,0 +1,145 @@
+{
+  "funifier-create-trigger": [
+    "knowledge/modules/trigger.md",
+    "knowledge/guides/triggers-guide.md",
+    "knowledge/guides/java-entities.md",
+    "knowledge/guides/java-managers.md",
+    "knowledge/guides/trigger-examples.md"
+  ],
+  "funifier-create-scheduler": [
+    "knowledge/modules/scheduler.md",
+    "knowledge/guides/java-managers.md",
+    "knowledge/guides/java-libraries.md"
+  ],
+  "funifier-create-aggregate": [
+    "knowledge/guides/aggregates.md",
+    "knowledge/guides/database-access.md",
+    "knowledge/modules/database.md"
+  ],
+  "funifier-date-handling": [
+    "knowledge/guides/database-access.md",
+    "knowledge/guides/aggregates.md",
+    "knowledge/modules/database.md"
+  ],
+  "funifier-create-challenge": [
+    "knowledge/modules/challenge.md",
+    "knowledge/modules/action.md",
+    "knowledge/modules/point.md"
+  ],
+  "funifier-create-action": [
+    "knowledge/modules/action.md",
+    "knowledge/modules/action-log.md"
+  ],
+  "funifier-create-audit": [
+    "knowledge/modules/audit.md",
+    "knowledge/modules/database.md"
+  ],
+  "funifier-create-point": [
+    "knowledge/modules/point.md",
+    "knowledge/modules/achievement.md"
+  ],
+  "funifier-create-level": [
+    "knowledge/modules/level.md",
+    "knowledge/modules/point.md"
+  ],
+  "funifier-create-leaderboard": [
+    "knowledge/modules/leaderboard.md",
+    "knowledge/modules/point.md",
+    "knowledge/modules/action.md"
+  ],
+  "funifier-create-quiz": [
+    "knowledge/modules/quiz.md",
+    "knowledge/modules/question.md"
+  ],
+  "funifier-create-virtual-good": [
+    "knowledge/modules/virtual-good.md",
+    "knowledge/modules/point.md"
+  ],
+  "funifier-create-custom-page": [
+    "knowledge/modules/studio-page.md",
+    "knowledge/guides/aggregates.md",
+    "knowledge/modules/auth.md"
+  ],
+  "funifier-implement-frontend": [
+    "knowledge/modules/auth.md",
+    "knowledge/guides/aggregates.md",
+    "knowledge/guides/database-access.md",
+    "knowledge/modules/patterns.md",
+    "knowledge/modules/action-log.md",
+    "knowledge/modules/static-repo.md"
+  ],
+  "funifier-debug": [
+    "knowledge/guides/java-libraries.md",
+    "knowledge/modules/trigger.md",
+    "knowledge/guides/triggers-guide.md",
+    "knowledge/guides/trigger-examples.md",
+    "knowledge/modules/scheduler.md",
+    "knowledge/guides/aggregates.md",
+    "knowledge/modules/public.md"
+  ],
+  "funifier-help": [
+    "knowledge/index.md"
+  ],
+  "funifier-manage-player": [
+    "knowledge/modules/player.md"
+  ],
+  "funifier-manage-team": [
+    "knowledge/modules/team.md"
+  ],
+  "funifier-create-competition": [
+    "knowledge/modules/competition.md"
+  ],
+  "funifier-create-folder": [
+    "knowledge/modules/folder.md"
+  ],
+  "funifier-create-lottery": [
+    "knowledge/modules/lottery.md"
+  ],
+  "funifier-create-mystery": [
+    "knowledge/modules/mystery.md"
+  ],
+  "funifier-create-story": [
+    "knowledge/modules/story.md"
+  ],
+  "funifier-create-crossword": [
+    "knowledge/modules/crossword.md"
+  ],
+  "funifier-create-notification": [
+    "knowledge/modules/notification.md"
+  ],
+  "funifier-create-lastmile": [
+    "knowledge/modules/lastmile.md"
+  ],
+  "funifier-create-webhook": [
+    "knowledge/modules/webhook.md"
+  ],
+  "funifier-create-websocket": [
+    "knowledge/modules/websocket.md"
+  ],
+  "funifier-create-widget": [
+    "knowledge/modules/widget.md"
+  ],
+  "funifier-create-swap": [
+    "knowledge/modules/swap.md"
+  ],
+  "funifier-create-custom-object": [
+    "knowledge/modules/custom-object.md",
+    "knowledge/modules/database.md"
+  ],
+  "funifier-configure-security": [
+    "knowledge/modules/security.md"
+  ],
+  "funifier-import-csv": [
+    "knowledge/modules/csv-data.md"
+  ],
+  "funifier-upload-file": [
+    "knowledge/modules/upload.md"
+  ],
+  "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,6 +1,42 @@
 {
-  "generatedAt": "2026-06-11T23:04: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": "a05c3dc778b494d2d9d781787dd2231c1ae5720c3e368b41071f02df85a1a922",
       "status": "verified",
@@ -537,7 +573,7 @@
       ]
     },
     "funifier-help": {
-      "configHash": "3880c7e32947710dcf855641e2822bc5eead0d39b8910305ec7bc2706a1196ca",
+      "configHash": "1da15e3fcabe8f807cab51fcfbba47686a1a4c03407b6808f5364c314f963908",
       "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 |
 
 ---