agent-engineering-skills 1.0.0

package/skills/security/input-trust-audit/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: input-trust-audit
+description: Identifies values that should never be trusted from the client (userId, role, price, XP, permissions, ownership, status, reward, timestamps) and verifies the server derives them from the session or database instead of the request payload.
+category: security
+triggers:
+  - "audit input trust"
+  - "what should not be trusted from the client"
+  - "server-side derivation of role price xp"
+  - "mass assignment and client-supplied ownership"
+  - "never trust the frontend"
+priority: high
+---
+
+# Input Trust Audit
+
+## Objective
+
+Ensinar o agente a identificar **quais valores nunca devem ser confiados ao cliente** e
+a verificar que o servidor os deriva da sessão ou do banco, não do payload do request.
+A regra central (também em `AGENTS.md`): não confiar no frontend.
+
+```text
+userId   role   price   XP   permissions   ownership   status   reward   timestamps
+```
+
+Cada um destes é um valor de *autoridade* — algo que determina identidade, permissão,
+valor, ou ordem. Se o servidor lê do payload, o cliente pode forjar.
+
+## When to Use
+
+* Em qualquer endpoint que aceita um body/params com campos sensíveis.
+* Ao auditar mass assignment, client-supplied IDs, preços/XP do cliente, timestamps do
+  cliente.
+* Quando o pedido menciona "input trust", "never trust the frontend", "mass
+  assignment", "client-supplied role/price/ownerId".
+* **Composição:** pareia com `authorization-audit` (ownership/role do cliente =
+  bypass de authz), `api-abuse-audit` (campos extra = mass assignment), `business-logic-audit` (price/XP/reward como regras), `gamification-audit` (XP/reward do
+  cliente), `edge-case-hunter` (valores forjados como edge cases).
+
+## Mental Model
+
+Todo input do cliente é *não-confiável por default*. A pergunta não é "isto é seguro?"
+mas "o servidor *deriva* este valor ou *aceita* este valor?". Derivar = ler da sessão
+autenticada, do banco, ou calcular server-side. Aceitar = ler do body/params e gravar.
+
+A lista canônica de valores de autoridade (do `plan.md` §7):
+
+| Valor | Por que não confiar | De onde derivar |
+|---|---|---|
+| `userId` | forjar identidade | sessão/token (`token.sub`) |
+| `role` | escalar privilégio | sessão/DB, nunca body |
+| `price` | zerar/inverter custo | catálogo/DB server-side |
+| `XP` | inflar recompensa | calcular server-side pelo evento |
+| `permissions` | auto-conceder | sessão/DB |
+| `ownership` | reivindicar recurso alheio | DB (recurso.ownerId == caller) |
+| `status` | forçar estado (paid/active) | transição server-side validada |
+| `reward` | auto-recompensar | determinado server-side pelo trigger |
+| `timestamps` | manipular ordem/expiração | `now()` server-side ou DB default |
+
+O bug: o handler faz `user.role = body.role` ou `order.price = body.price` ou
+`grant.xp = body.xp`. O cliente envia o que quiser.
+
+Variante: **mass assignment** — o servidor binda todo o body ao modelo e grava campos
+que a UI nem envia (`role`, `isAdmin`), porque não há allowlist.
+
+## Investigation Procedure
+
+1. **Listar todos os campos** que cada endpoint relevante aceita no body/params.
+2. **Rotular cada campo**: não-sensível (nome, bio, preferência) vs **valor de
+   autoridade** (qualquer da lista canônica, ou qualquer campo que determine
+   identidade/permissão/valor/estado/ordem).
+3. **Para cada valor de autoridade, perguntar: o servidor deriva ou aceita?**
+   * `userId` — vem de `token.sub`/sessão, ou do body?
+   * `role` — vem da sessão/DB, ou do body?
+   * `price` — vem do catálogo/DB, ou do body?
+   * `XP`/`reward` — calculado server-side pelo evento, ou do body?
+   * `ownership` — validado contra o DB, ou confiado no body?
+   * `status` — transição validada server-side, ou setado do body?
+   * `timestamps` — `now()`/DB, ou do body?
+4. **Testar mass assignment** — envie campos não-enviados pela UI. Gravados?
+5. **Testar forjamento** — envie um valor de autoridade forjado (role=admin,
+   price=0, xp=99999). O servidor aceita e age?
+6. **Confirmar com evidência** — reproduza o forjamento e observe o efeito.
+7. **Reportar** via `templates/audit-report.md`.
+
+## Questions to Ask
+
+* Quais campos o endpoint aceita? Qual é a allowlist (se houver)?
+* `userId` no handler vem da sessão ou do body/query? (se do body, forja identidade)
+* `role`/`permissions` — lidos da sessão/DB ou do payload?
+* `price`/`amount` — do catálogo server-side ou do body?
+* `XP`/`reward`/`points` — calculados server-side ou enviados pelo cliente?
+* `ownerId`/`assignedTo` — validado contra o DB ou confiado?
+* `status` — o cliente pode setar direto (paid/active/deleted)?
+* `timestamps` (`createdAt`, `expiresAt`) — `now()` server-side ou do body?
+* Há bind automático do body ao modelo (mass assignment)? Qual allowlist o impede?
+* Um campo que a UI nunca envia — se eu enviar, é gravado?
+
+## Attack Patterns
+
+```text
+userId from body
+    POST /comment {postId, userId: <other>}     → comentário em nome de outro?
+    (correto: userId = token.sub, ignorar body.userId)
+
+role from body (mass assignment)
+    PUT /profile {bio, role:"admin"}            → role gravado?
+
+price from body
+    POST /checkout {itemId, price: 0}           → checkout grátis?
+    POST /checkout {itemId, price: -50}         → reembolso invertido?
+
+XP from body
+    POST /grant {userId, xp: 99999}             → quem chama define o XP?
+    (correto: xp calculado pela ação/evento server-side)
+
+ownership from body
+    POST /transfer {resourceId, toOwnerId}      → caller é dono? validado?
+
+status from body
+    POST /order/{id}/update {status:"paid"}     → cliente marca como pago?
+    (correto: transição só via gateway callback verificado)
+
+timestamps from body
+    POST /post {content, createdAt:"1970-..."}  → data forjada? expired reanimado?
+
+permissions from body
+    PUT /user/{id} {permissions:["*"]}          → auto-concessão?
+
+mass assignment via generic bind
+    handler: model.update(req.body)             → sem allowlist → todos os campos
+    enviar {isAdmin: true}                       → gravado?
+```
+
+## Evidence Requirements
+
+* **Nomear o campo** e classificá-lo (valor de autoridade da lista canônica, ou outro
+  sensível).
+* **Mostrar de onde o servidor lê** — session/DB vs body/params. Cite a linha/mecanismo.
+* **Mostrar o forjamento** — request com o valor forjado e o efeito observado.
+* **Escalar confiança:**
+  * `CONFIRMED` — reproduziu o forjamento e observou o efeito (role virou admin, price
+    zerou, XP inflou).
+  * `HIGH CONFIDENCE` — handler visivelmente lê do body um valor de autoridade, sem
+    reprodução.
+  * `POSSIBLE` — campo suspeito aceito, efeito não confirmado.
+  * `SPECULATIVE` — "deveria ser derivado" sem rastrear.
+* Forjamento de `role`/`permissions`/`ownership` que escala privilégio = mínimo
+  `HIGH CONFIDENCE` se reproduzido.
+
+## False Positives
+
+* **Servidor deriva corretamente** — se `userId = token.sub`, `role` da sessão, `price`
+  do catálogo, "campo no body" é ignorado. Confirmar que o servidor *ignora* o campo
+  antes de reportar.
+* **Allowlist de campos** — se o bind usa uma allowlist explícita (`{bio, name}`) e
+  descarta o resto, mass assignment é defendido. Confirmar a allowlist.
+* **Campo é legítimo do cliente** — `bio`, `displayName`, `preferences` *devem* vir do
+  cliente. Não reportar como "input trust" o que é input legítimo.
+* **Timestamp do cliente é referência, não autoridade** — se `scheduledAt` é um input
+  legítimo de agendamento (com validação), não é o mesmo que forjar `createdAt`.
+* **Status via callback verificado** — se `paid` só é setado pelo callback do gateway
+  com assinatura/verificação, o cliente não pode forjar. Confirmar o caminho.
+* **Role do body é validado contra a sessão** — se o servidor aceita `role` no body mas
+  só permite transições que o caller já tem, é defensivo. Raro; confirmar.
+
+## Output Format
+
+Para cada valor de autoridade aceito (não derivado) do cliente, um finding via
+`templates/audit-report.md`. Em **Reproduction**, dê o request com o valor forjado e o
+efeito. Em **Affected component**, nomeie o endpoint e o campo. Em **Root cause**, diga
+que o servidor lê do body em vez de derivar (cite onde), ou que falta allowlist (mass
+assignment). Em **Recommendation**, indique derivação server-side (token.sub, catálogo,
+cálculo por evento) e allowlist de campos no bind.
+
+Apresente a tabela de campos por endpoint (campo | sensível? | derivado ou aceito? |
+✓/✗). Privilégios (`role`/`permissions`/`ownership`) e valor (`price`/`XP`/`reward`)
+primeiro; timestamps e status depois.

package/templates/audit-report.md

@@ -0,0 +1,89 @@
+# Audit Report Template
+
+Template para relatórios de auditoria. Toda skill de auditoria produz findings neste
+formato. Copie este template e preencha. Ver `AGENTS.md` § 2 para a escala de evidência
+e `docs/skill-authoring.md` para a estrutura de skills.
+
+---
+
+# Audit Report — <target>
+
+**Date:** <YYYY-MM-DD>
+**Target:** <system / component / feature audited>
+**Scope:** <what was in scope; what was explicitly out of scope>
+**Skills used:** <comma-separated skill names, e.g. adversarial-review, business-logic-audit>
+**References consulted:** <names from references/*.yaml, or "none">
+
+## Summary
+
+<1–3 paragraphs. Número total de findings por severidade. As 2–3 conclusões mais
+importantes. Não listar todos os findings aqui — apenas o que um humano precisa saber
+primeiro.>
+
+### Findings by severity
+
+| Severity | Count |
+|---|---|
+| Critical | <n> |
+| High | <n> |
+| Medium | <n> |
+| Low | <n> |
+
+### Findings by confidence
+
+| Confidence | Count |
+|---|---|
+| CONFIRMED | <n> |
+| HIGH CONFIDENCE | <n> |
+| POSSIBLE | <n> |
+| SPECULATIVE | <n> |
+
+> Findings `SPECULATIVE` são riscos a verificar, **não** bugs confirmados. Não devem
+> bloquear implementação.
+
+---
+
+## Findings
+
+### Finding 1 — <short title>
+
+| Field | Value |
+|---|---|
+| **Severity** | Critical \| High \| Medium \| Low |
+| **Confidence** | CONFIRMED \| HIGH CONFIDENCE \| POSSIBLE \| SPECULATIVE |
+| **Affected component** | <file(s) / module(s) / endpoint(s)> |
+| **Affected flow** | <the user or system flow this breaks> |
+| **Reproduction** | <step-by-step, or request sequence; concrete enough to redo> |
+| **Expected behavior** | <what should happen> |
+| **Actual behavior** | <what does happen> |
+| **Root cause** | <the mechanism — why it happens, not just that it does> |
+| **Impact** | <what an attacker or user can achieve; blast radius> |
+| **Recommendation** | <concrete fix; where to enforce it (server, DB, both)> |
+
+**Evidence:** <logs, test output, request/response, or "no reproduction yet — reasoning only". Link or paste.>
+
+**False-positive check:** <why this is NOT an acceptable/intended behavior — or "considered: <X>; ruled out because <Y>". If you cannot rule it out, lower confidence.>
+
+---
+
+### Finding 2 — <short title>
+
+<repeat the block above for each finding>
+
+---
+
+## Deduplication note
+
+<Se múltiplas skills apontaram o mesmo defeito, registre aqui quais foram consolidadas
+em um único finding e por quê. Se nenhuma sobreposição, escreva "No overlapping findings
+across skills.">
+
+## Out of scope / not investigated
+
+<Quais áreas foram deixadas de fora e por quê — para que um leitor saiba o que NÃO foi
+verificado. Honestidade sobre limites é parte do relatório.>
+
+## Next steps
+
+<Ordenado por prioridade. Quais findings exigem ação imediata, quais são riscos a
+monitorar, quais precisam de mais investigação para subir de POSSIBLE para CONFIRMED.>

package/templates/bug-report.md

@@ -0,0 +1,107 @@
+# Bug Report Template
+
+Template para relatórios de bugs individuais. Cada bug é um documento autônomo que pode
+ser referenciado, anexado a uma issue, ou consolidado em um `audit-report.md` maior.
+
+---
+
+# Bug Report — <short title>
+
+**Date:** <YYYY-MM-DD>
+**Target version:** <version / commit / environment>
+**Reported by:** <skill name(s) + methodology>
+
+## Summary
+
+<1-3 frases. O que está acontecendo e por que é um bug.>
+
+## Severity
+
+| Critical | High | Medium | Low |
+|---|---|---|---|
+
+## Confidence
+
+| CONFIRMED | HIGH CONFIDENCE | POSSIBLE | SPECULATIVE |
+|---|---|---|---|
+
+*Ver `AGENTS.md` § 2 para a escala de evidência.*
+
+## Affected component
+
+<file(s) / module(s) / endpoint(s) / route(s) — ex: `src/app/api/checkout/route.ts`>
+
+## Affected flow
+
+<O fluxo que este bug afeta — ex: "fluxo de criação de pedido, etapa de cobrança">
+
+## Reproduction
+
+### Steps
+
+1. `<passo 1>`
+2. `<passo 2>`
+3. `<passo 3>`
+
+### Request/response
+
+```http
+<request exato — método, path, headers, body>
+```
+
+```http
+<response observada>
+```
+
+### Environment
+
+- **Browser:** Chrome 120 / Firefox 115 / Safari 17
+- **Platform:** Mobile / Desktop / Tablet
+- **Auth state:** Authenticated / Unauthenticated / Role: admin
+- **Data state:** <estado prévio necessário: saldo, recursos, flags>
+
+## Expected behavior
+
+<O que deveria acontecer, segundo a especificação, regra de negócio, ou princípio.>
+
+## Actual behavior
+
+<O que de fato acontece — o comportamento incorreto.>
+
+## Root cause
+
+<O mecanismo — por que acontece, não só que acontece. Ex: "o handler não checa
+ownership porque o middleware de authz não cobre esta rota", "o incremento é lido do
+cache e reescrito sem atomicidade".>
+
+## Impact
+
+* **Blast radius:** <quantos usuários, recursos, transações?>
+* **Data loss:** <sim / não / parcial — qual dado?>
+* **Exploitability:** <trivial / médio / difícil — o que o atacante precisa?>
+
+## Recommendation
+
+```text
+<Ação concreta. Onde e como corrigir. Ex: "Adicionar checagem de ownership no handler
+DELETE /order/{id} antes de executar a deleção.">
+```
+
+## Evidence
+
+<logs, screenshots, video, request/response adicional, ou "não reproduzido — apenas
+análise de código".>
+
+## False-positive check
+
+*Por que isto NÃO é comportamento aceitável ou intencional:*
+
+- <se já considerou: "talvez seja intencional porque..."> → <ruled out: documentação /
+  regra de negócio / produto confirma>
+- <se não consegue ruled out: baixar confiança para POSSIBLE e marcar como "precisa
+  decisão de produto">
+
+## References
+
+<skills usadas, referências consultadas em `references/*.yaml`, links para código
+relevante.>

package/templates/design-review.md

@@ -0,0 +1,122 @@
+# Design Review Template
+
+Template para revisões de design de frontend (UX + visual + interação + animação +
+acessibilidade + referências externas). Consolida a saída das skills de frontend em um
+relatório único, com síntese de pesquisa quando aplicável.
+
+---
+
+# Design Review — <screen / flow>
+
+**Date:** <YYYY-MM-DD>
+**Target:** <tela/fluxo/componente revisado>
+**Skills used:** <ex: ux-review, visual-quality-review, interaction-design,
+animation-review, accessibility-review>
+**References consulted:** <fontes de references/frontend.yaml + ux.yaml usadas>
+
+## Executive summary
+
+<2-3 parágrafos. O que está bom, o que está quebrado, e o que deve ser corrigido antes
+de lançar. Prioridade geral (ship / ship-with-fixes / fix-first).>
+
+## Verdict
+
+| **Ship** | **Ship with fixes** | **Fix first** |
+|---|---|---|
+
+## Dimensions
+
+Para cada dimensão, um veredicto resumido + pointer para os findings detalhados:
+
+| Dimension | Verdict | Findings |
+|---|---|---|
+| UX (clareza, hierarquia, carga cognitiva, feedback, affordances, consistência, navegação, empty states, erros, loading) | ✅ / ⚠️ / ❌ | #F1..F5 |
+| Visual (tipografia, spacing, hierarchy, density, contrast, composition, noise, AI slop) | ✅ / ⚠️ / ❌ | #F6..F8 |
+| Interaction (hover, focus, pressed, disabled, loading, transitions, feedback, micro-interactions) | ✅ / ⚠️ / ❌ | #F9..F10 |
+| Animation (propósito, timing, easing, hierarchy, continuity, interruption, reduced motion) | ✅ / ⚠️ / ❌ | #F11 |
+| Accessibility (keyboard, SR, focus, semantic HTML, contrast, touch targets, reduced motion, forms, errors) | ✅ / ⚠️ / ❌ | #F12..F14 |
+
+---
+
+## Findings
+
+### Finding 1 — <short title>
+
+| Field | Value |
+|---|---|
+| **Severity** | Critical \| High \| Medium \| Low |
+| **Confidence** | CONFIRMED \| HIGH CONFIDENCE \| POSSIBLE \| SPECULATIVE |
+| **Dimension** | UX \| Visual \| Interaction \| Animation \| Accessibility |
+| **Affected component** | <elemento/tela> |
+| **Affected flow** | <fluxo> |
+| **Reproduction** | <o que o usuário vê vs o que deveria ver> |
+| **Expected behavior** | <esperado> |
+| **Actual behavior** | <observado> |
+| **Root cause** | <princípio violado — ex: "contraste 2.9:1 falha WCAG 1.4.3", "focus ring removido com `outline: none`", "empty state sem CTA"> |
+| **Impact** | <consequência para o usuário> |
+| **Recommendation** | <correção concreta> |
+
+---
+
+### Finding N — <short title>
+
+<repetir o bloco acima>
+
+---
+
+## Research synthesis (se pesquisa foi realizada)
+
+*Usar o formato de síntese de pesquisa do `AGENTS.md` § 5. Ex:*
+
+## Research
+
+### Reference
+[Impeccable]
+
+### Relevant Pattern
+Espaçamento consistente baseado em 4px, hierarquia tipográfica clara, ausência de
+decoração sem função.
+
+### Why It Matters
+O que separa design de "amador" de "profissional" é a consistência rítmica e a
+disciplina visual.
+
+### Adaptation
+Aplicar o sistema de 4px no spacing dos cards da dashboard, que hoje varia
+aleatoriamente.
+
+### Trade-offs
+Requer auditoria de todos os componentes existentes para uniformizar.
+
+### Recommendation
+Adotar as 3 primeiras regras do Impeccable (spacing system, type scale, no-orphan
+decoration) como padrão do projeto.
+
+---
+
+## Accessibility checklist (WCAG spot-check)
+
+| Check | Pass | Fail | N/A |
+|---|---|---|---|
+| Keyboard reachable (all interactive elements) | | | |
+| Focus visible (no `outline: none` without substitute) | | | |
+| Focus trap correct in modals | | | |
+| Alt text on informative images | | | |
+| aria-label on semantic icons | | | |
+| aria-live on dynamic content | | | |
+| Semantic HTML (`<button>`, `<nav>`, `<h1-h6>`) | | | |
+| Text contrast ≥ 4.5:1 | | | |
+| Touch targets ≥ 44×44px | | | |
+| `<label>` on every form input | | | |
+| Errors text + aria-live (not color-only) | | | |
+| `prefers-reduced-motion` respected | | | |
+
+---
+
+## Out of scope / not reviewed
+
+<O que não foi revisado e por quê.>
+
+## Next steps
+
+<Priorizado. Fix-first findings primeiro; riscos a monitorar depois.>

package/templates/research-report.md

@@ -0,0 +1,96 @@
+# Research Report Template
+
+Template para relatórios de pesquisa. Consolida a saída das research skills
+(`reference-research`, `github-reference-research`, `market-research`,
+`implementation-research`) em um documento único com síntese obrigatória — nunca apenas
+uma lista de links (ver `AGENTS.md` § 5).
+
+---
+
+# Research Report — <question / feature / problem>
+
+**Date:** <YYYY-MM-DD>
+**Research question:** <a pergunta que guiou a pesquisa>
+**Problem type:** <animation | ux | visual | architecture | security | engineering |
+  product | implementation | discovery>
+**Research level:** <none | proportional | full> *(proporcional a uncertainty +
+impact + irreversibility — ver `AGENTS.md` § 6)*
+**Skills used:** <ex: reference-research, github-reference-research, market-research>
+**Router:** <research-router → qual despacho>
+
+## Executive summary
+
+<1-2 parágrafos. A resposta direta à research question, a recomendação principal, e o
+nível de confiança geral.>
+
+---
+
+## Research
+
+### Reference
+[Name]
+
+### Relevant Pattern
+O que foi encontrado.
+
+### Why It Matters
+Por que este padrão é útil.
+
+### Adaptation
+Como ele poderia se aplicar ao projeto atual.
+
+### Trade-offs
+Que problemas ele introduz.
+
+### Recommendation
+O que deve de fato ser adotado.
+
+---
+
+### Reference 2 — <name>
+
+<repetir o bloco de síntese. Consolidar em um bloco quando múltiplas fontes dão a mesma
+recomendação; citar as fontes no cabeçalho.>
+
+---
+
+## Convergence & divergence (para market research)
+
+### Convergência (adotar)
+- <onde os produtos/fontes concordam — padrão maduro>
+
+### Divergência (avaliar)
+- <onde divergem — espaço para diferenciação ou decisão>
+
+---
+
+## Sources & authority
+
+| Source | Type | Authority | Used for |
+|---|---|---|---|
+| <name> | methodology \| heuristic \| inspiration \| implementation \| discovery | established \| vendor \| community \| curated | <o que se extraiu> |
+
+> **Inspiração ≠ evidência** — fontes `type: inspiration` / `authority: curated`
+> (ex: Dribbble, dark.design) calibram gosto, nunca justificam uma decisão técnica
+> (ver `AGENTS.md` § 1).
+
+## Confidence assessment
+
+*Classifique a confiança da recomendação como um todo, não por fonte:*
+
+| CONFIRMED | HIGH CONFIDENCE | POSSIBLE | SPECULATIVE |
+|---|---|---|---|
+
+- **O que confirmaria/subiria a confiança:** <ex: "protótipo com usuários reais",
+  "teste de carga", "prova de conceito no contexto">
+- **O que é incerto:** <ex: "padrão observado em 1 produto apenas", "benchmark de
+  artigo de 2023">
+
+## Out of scope / not researched
+
+<O que não foi pesquisado e por quê (proporcionalidade, custo, irrelevância).>
+
+## Next steps
+
+<Próximas ações: prova de conceito, teste com usuários, protótipo, ou decisão de
+implementação já tomada.>