funifier-mcp 0.3.17 → 0.3.18

package/skills/funifier/references/audit-permissions.md

@@ -0,0 +1,89 @@
+# funifier-audit-permissions
+
+Cross-check a project's Funifier API calls against the live security document — scan code for usage, build an evidence-backed manifest, run the deterministic audit engine, and report missing scopes, excess tokens, and static danger findings; use when debugging 401s, auditing minimum privilege, or verifying permissions before deploying; audit is read-only and never changes any configuration
+
+---
+
+## Before starting — find relevant docs
+
+Use the `funifier_search_docs` MCP tool to load only what you need:
+
+```
+funifier_search_docs "audit permissions security scope 401 missing-scope excess-token danger manifest bearer basic app-secret role least-privilege"
+```
+
+Then read the most relevant results with `funifier_read_doc path=<path>`.
+
+## Primary docs for this skill
+
+If search returns insufficient results, read these directly:
+
+- `funifier_read_doc path=guides/permission-audit`
+- `funifier_read_doc path=modules/security`
+
+## Steps
+
+## Regras críticas
+
+- **O audit é read-only.** Nenhuma configuração é alterada. O MCP apenas lê o documento de segurança e avalia o manifest.
+- **Bearer tokens embtem o scope no login.** Corrigir o role não invalida tokens existentes — o jogador precisa fazer login novamente.
+- **Excess findings podem ser necessários** a consumidores fora deste manifest. Verifique antes de remover qualquer token.
+- **Low-confidence entries** (URLs dinâmicas ou wrappers): use `"confidence": "low"` e um path com o prefixo mais específico possível. Nunca omita chamadas suspeitas.
+
+---
+
+## Steps
+
+### 1. Descobrir chamadas Funifier no projeto
+
+Procure no código todas as chamadas à API Funifier (endpoints, métodos HTTP e mecanismo de auth):
+
+- **Com GitNexus indexado:** `gitnexus_query("funifier API calls")` para localizar call sites
+- **Fallback (busca em código):** grep por `/v3/`, `funifier`, `apiKey`, `app_secret`, `Authorization`
+- Para cada chamada, registre: `method`, `path`, `auth context` (ver tabela em `guides/permission-audit.md` §2), e `file:line` como `evidence`
+- Classifique o auth:
+  - Sem secret / token público → `"public"`
+  - Player Bearer → `"player"`
+  - App secret em config/env → `"app:<name>"` (use o `name` da entrada em `apps[]`)
+
+### 2. Montar o manifest
+
+Construa o JSON seguindo o schema de `guides/permission-audit.md` §3. Exemplo mínimo:
+
+```json
+{
+  "version": 1,
+  "entries": [
+    { "method": "GET",  "path": "/v3/player/me",    "auth": "player",      "evidence": "src/api.ts:12" },
+    { "method": "POST", "path": "/v3/action/log",   "auth": "player",      "evidence": "src/events.ts:58" },
+    { "method": "POST", "path": "/v3/player",        "auth": "app:backend", "evidence": "workers/sync.ts:34" },
+    { "method": "GET",  "path": "/v3/database/orders", "auth": "app:backend", "evidence": "workers/sync.ts:80" }
+  ]
+}
+```
+
+Para chamadas com URL dinâmica: use o prefixo mais específico e defina `"confidence": "low"`.
+
+### 3. Executar o audit
+
+```
+funifier_permissions action=audit data=<manifest JSON>
+```
+
+O resultado inclui:
+- `missing`: chamadas que seriam negadas — 401 em produção. Campo `requiredTokens` indica o token mínimo.
+- `excess`: tokens concedidos que nenhuma entrada requer. Campo `narrowingSuggestion` para broad tokens.
+- `danger`: riscos estáticos no documento de segurança (independentes do manifest).
+- `manual-review`: tokens não verificáveis por análise de paths (`cross_domain`, `write_upload`, etc.).
+- `missing-principal`: auth context referenciado no manifest não existe no documento de segurança.
+
+### 4. Apresentar o relatório e encaminhar remediação
+
+Apresente os findings agrupados por severidade (`missing` primeiro). Para cada `missing`:
+- Indique o token exato necessário (`requiredTokens`), a chamada e a evidência.
+- **Não aplique a correção automaticamente.** Apresente a ação sugerida ao utilizador e aguarde aprovação.
+- Quando aprovado: `funifier_permissions action=save_security_role` ou `save_api_app` (cada mutação cria backup automático).
+
+Para `excess`: adverta que o token pode ser necessário a consumidores fora deste manifest antes de sugerir remoção.
+
+Para `danger`: explique o risco e sugira remoção ou restrição do scope afetado como ação separada.