@lugom.io/hefesto 0.3.0 → 1.0.0

package/skills/hefesto-init/references/web.md

@@ -0,0 +1,246 @@
+# Preset: Web
+
+## Stack
+
+- Next.js (App Router) + TypeScript
+- TailwindCSS + shadcn/ui
+- Vitest + Playwright
+- ESLint + Prettier
+- T3 Env + Zod
+- pnpm (package manager)
+
+## Scaffold
+
+### 1. Criar projeto Next.js
+
+```bash
+pnpx create-next-app@latest . --typescript --tailwind --eslint --app --src-dir --import-alias "@/*" --turbopack --yes
+```
+
+Após o scaffold, deletar arquivos genéricos gerados: `rm -f CLAUDE.md AGENTS.md`
+
+**Diretório não vazio:** se `.hefesto/` ou `package.json` já existem, criar num subdiretório temporário e mover:
+
+```bash
+pnpx create-next-app@latest .tmp-scaffold --typescript --tailwind --eslint --app --src-dir --import-alias "@/*" --turbopack --yes
+mv .tmp-scaffold/* . && mv .tmp-scaffold/.gitignore . 2>/dev/null && mv .tmp-scaffold/.eslintrc* . 2>/dev/null
+rmdir .tmp-scaffold
+rm -f CLAUDE.md AGENTS.md
+```
+
+### 2. shadcn/ui
+
+```bash
+pnpx shadcn@latest init -d
+```
+
+### 3. Prettier
+
+```bash
+pnpm add -D prettier prettier-plugin-tailwindcss eslint-config-prettier
+```
+
+Criar `.prettierrc` (semi, singleQuote, trailingComma all, plugin tailwindcss). Criar `.prettierignore` (node_modules, .next, dist, coverage, .claude, .hefesto). Adicionar `eslint-config-prettier` ao ESLint config.
+
+Scripts: `format`, `format:check`.
+
+### 4. Vitest
+
+```bash
+pnpm add -D vitest @vitejs/plugin-react @testing-library/react @testing-library/dom @testing-library/user-event @testing-library/jest-dom jsdom vite-tsconfig-paths
+```
+
+Criar `vitest.config.ts` (jsdom, react plugin, tsconfigPaths, setup em `tests/setup.ts`, include `src/**/*.test.*` e `tests/unit/**`). Criar `tests/setup.ts` com import de `@testing-library/jest-dom/vitest`.
+
+Scripts: `test`, `test:watch`, `test:coverage`.
+
+### 5. Playwright
+
+```bash
+pnpm add -D @playwright/test
+pnpx playwright install --with-deps chromium
+```
+
+Criar `playwright.config.ts` (testDir `tests/e2e`, baseURL localhost:3000, webServer com `pnpm dev`).
+
+Script: `test:e2e`.
+
+### 6. T3 Env + Zod
+
+```bash
+pnpm add @t3-oss/env-nextjs zod
+```
+
+Criar `src/lib/env.ts` com `createEnv` (server: NODE_ENV, client: vazio). Importar `./src/lib/env.ts` no topo de `next.config.ts`. Criar `.env.example`. Adicionar `.env`, `.env.local`, `.env.production` ao `.gitignore`.
+
+### 7. Limpar boilerplate
+
+- `src/app/page.tsx` → página limpa com `<h1>` do nome do projeto
+- `src/app/globals.css` → apenas imports Tailwind + variáveis shadcn
+- Remover assets padrão em `public/` (next.svg, vercel.svg)
+- Simplificar `src/app/layout.tsx`
+
+### 8. Criar estrutura feature-based
+
+```bash
+mkdir -p src/features src/hooks src/services src/types tests/unit tests/e2e
+```
+
+Criar `.gitkeep` nos diretórios vazios.
+
+### 9. Formatação inicial
+
+```bash
+pnpm format
+```
+
+---
+
+## Arquitetura e Convenções
+
+### Feature-based
+
+Código organizado por domínio em `src/features/`. Cada feature:
+
+```
+src/features/<nome>/
+├── components/     ← componentes da feature
+├── hooks/          ← hooks da feature
+├── services/       ← lógica de negócio e chamadas de API
+├── types/          ← tipos e interfaces
+└── index.ts        ← barrel export (API pública)
+```
+
+Compartilhado entre features fica em `src/` raiz: `components/`, `components/ui/` (shadcn), `hooks/`, `services/`, `types/`, `lib/`.
+
+### Princípios
+
+1. **Features não importam de outras features.** Código compartilhado sobe para `src/`.
+2. **`src/app/` só contém rotas e layouts.** Lógica fica em `src/features/`.
+3. **Barrel exports** — importar do índice: `import { LoginForm } from '@/features/auth'`.
+4. **Sem `any`** — usar `unknown` e narrowing.
+5. **Validação nas bordas** — inputs de usuário e APIs externas com Zod.
+6. **Env validado** — usar `env` de `@/lib/env`, nunca `process.env` direto.
+
+### Naming
+
+| Elemento    | Convenção          | Exemplo                |
+| ----------- | ------------------ | ---------------------- |
+| Componentes | PascalCase         | `ProductCard.tsx`      |
+| Hooks       | useCamelCase       | `useProducts.ts`       |
+| Serviços    | camelCase.service  | `auth.service.ts`      |
+| Tipos       | PascalCase         | `User`, `AuthResult`   |
+| Constantes  | SCREAMING_SNAKE    | `MAX_ITEMS_PER_PAGE`   |
+| Testes      | .test.ts/.test.tsx | `auth.service.test.ts` |
+
+### Testes
+
+- **Co-localizados** (`src/**/*.test.ts`) — lógica de negócio. Ficam ao lado do arquivo.
+- **De feature** (`tests/unit/`) — testes criados pelo Argos para validar requisitos. Nome: `feat-NNN-slug.test.ts`.
+- **E2E** (`tests/e2e/`) — fluxos críticos com Playwright.
+
+### Next.js 16 — `proxy.ts`
+
+No Next.js 16, `middleware.ts` foi substituído por `proxy.ts` (runtime Node.js em vez de Edge). Função exportada: `proxy` em vez de `middleware`. Para migrar: `npx @next/codemod@canary middleware-to-proxy .`
+
+Para proteção de rotas, preferir Server Components com `redirect()`.
+
+---
+
+## Receitas
+
+Padrões prontos para adotar conforme a feature precisar. **Não são instaladas no scaffold** — usar quando o projeto demandar.
+
+### Data Fetching — TanStack Query
+
+**Quando:** a feature precisa buscar, cachear ou sincronizar dados do servidor.
+
+```bash
+pnpm add @tanstack/react-query @tanstack/react-query-devtools
+```
+
+Setup: criar `src/lib/query-client.ts` com `QueryClient` configurado (staleTime, gcTime). Criar `src/components/providers.tsx` com `QueryClientProvider` wrapping children + `ReactQueryDevtools` em dev. Adicionar o provider no `layout.tsx` (como Client Component).
+
+Pattern de uso em features:
+
+```
+src/features/products/
+├── hooks/
+│   └── use-products.ts    ← useQuery + queryKey + fetch function
+├── services/
+│   └── products.service.ts ← fetch functions puras (sem hooks)
+```
+
+Hooks chamam services. Services são funções puras testáveis. Query keys seguem padrão `[feature, ...params]`.
+
+### Formulários — React Hook Form + Zod
+
+**Quando:** a feature tem formulários com validação.
+
+```bash
+pnpm add react-hook-form @hookform/resolvers
+```
+
+Zod já está na stack. Usar `zodResolver` com `useForm`. Integrar com componentes `Form` do shadcn/ui (`npx shadcn@latest add form`).
+
+Pattern: schema Zod define a validação, `useForm` gerencia o state, shadcn/ui `FormField` renderiza.
+
+### Estado Global — Zustand
+
+**Quando:** estado precisa ser compartilhado entre features sem prop drilling. Preferir para estado de UI (sidebar aberta, tema, filtros). Para dados do servidor, usar TanStack Query.
+
+```bash
+pnpm add zustand
+```
+
+Pattern: um store por domínio em `src/features/<nome>/stores/`. Stores exportam hooks (`useCartStore`). Usar slices para stores complexas.
+
+### Autenticação — Better Auth
+
+**Quando:** a feature precisa de login, registro, sessões ou proteção de rotas.
+
+```bash
+pnpm add better-auth
+```
+
+Setup: criar `src/lib/auth.ts` (server) com `betterAuth()` configurando database adapter e providers (email/password, Google, GitHub). Criar `src/lib/auth-client.ts` com `createAuthClient()`. Criar API route em `src/app/api/auth/[...all]/route.ts`.
+
+Plugins úteis: `twoFactor()`, `magicLink()`, `organization()`.
+
+Pattern de proteção: Server Components usam `auth.api.getSession()` + `redirect()`. Client Components usam `authClient.useSession()`.
+
+### Banco de Dados — Drizzle ORM
+
+**Quando:** a feature precisa persistir dados.
+
+```bash
+pnpm add drizzle-orm postgres
+pnpm add -D drizzle-kit
+```
+
+Setup: criar `src/db/index.ts` (connection com `postgres` driver). Criar `src/db/schema/` com schemas por domínio. Criar `drizzle.config.ts` apontando para o schema e connection string via `env.ts`, com `out: './src/db/migrations'`.
+
+Estrutura:
+
+```
+src/db/
+├── index.ts          ← connection + export do db
+├── schema/
+│   ├── index.ts      ← re-export de todos os schemas
+│   └── users.ts
+└── migrations/       ← geradas pelo drizzle-kit (out: './src/db/migrations')
+```
+
+Adicionar `DATABASE_URL` ao T3 Env (`src/lib/env.ts`) e `.env.example`.
+
+Scripts: `db:generate` (`drizzle-kit generate`), `db:migrate` (`drizzle-kit migrate`), `db:studio` (`drizzle-kit studio`).
+
+Pattern: schemas em `src/db/schema/<dominio>.ts`, queries em `src/features/<nome>/services/`.
+
+---
+
+## config.json
+
+- platform: "web"
+- lang: "typescript"
+- monorepo: false

package/skills/hefesto-new-feature/SKILL.md

@@ -1,53 +1,87 @@
 ---
 name: hefesto-new-feature
-description: "Cria uma nova feature no Hefesto. Use /hefesto-new-feature para definir uma nova feature com visão, fluxo do usuário, requisitos e fases de implementação."
+description: >
+  Cria o spec de uma nova feature no Hefesto. Coleta visão e requisitos, propõe abordagens,
+  decompõe em fases risk-first com rastreabilidade de requisitos.
+  Usar com: /hefesto-new-feature. Gera o documento FEAT-NNN — para implementar, usar
+  /hefesto-execute depois.
 user-invocable: true
 disable-model-invocation: true
 ---
 
 # Hefesto New Feature
 
-Cria um novo documento de feature em `.hefesto/features/`.
+Cria um novo documento de feature em `.hefesto/features/`. Guia o usuário desde a visão inicial até um spec completo com requisitos testáveis, fases de implementação ordenadas por risco, e rastreabilidade requisito→fase.
 
 ## Pré-requisitos
 
-Verificar se `.hefesto/` existe. Se não existir, sugerir `/hefesto-init` primeiro.
-
-## O que fazer
-
-1. Ler `.hefesto/templates/FEATURE.md` como base para o novo arquivo de feature.
-2. Ler `.hefesto/config.json` para obter o próximo ID disponível.
-3. Perguntar ao usuário:
-   - Título da feature (curto, descritivo)
-   - Visão (o que entrega e por que existe)
-   - Fluxo do usuário (passos que o usuário percorre)
-   - Requisitos principais (testáveis, centrados no usuário)
-   - O que está fora do escopo
-4. Com base nas respostas, propor fases de implementação:
-   - Cada fase deve ser atômica (executável em uma sessão)
-   - Listar arquivos que serão criados/modificados
-   - Definir tarefas concretas e critérios de aceitação
-5. Gerar o ID: `FEAT-NNN` onde NNN é o counter + 1, zero-padded.
-6. Gerar o slug a partir do título (lowercase, hifenizado, max 40 chars).
-7. Criar o arquivo `.hefesto/features/FEAT-NNN-slug.md` com o conteúdo.
-8. Atualizar `.hefesto/config.json` incrementando o counter.
-9. Atualizar `.hefesto/ROADMAP.md` adicionando a nova feature na tabela.
-10. Atualizar `.hefesto/STATE.md` se for a primeira feature ou se nenhuma estiver ativa.
-
-## Formato do arquivo
-
-O arquivo segue o template narrativo unificado com frontmatter YAML:
-
-```yaml
----
-id: FEAT-NNN
-title: "Título"
-status: draft
-created: YYYY-MM-DD
-updated: YYYY-MM-DD
-phases_total: N
-phases_done: 0
----
-```
+Verificar se `.hefesto/` existe. Se não, sugerir `/hefesto-init`.
+
+## Workflow
+
+### Fase 0 — Explorar Contexto
+
+Antes de perguntar, entender o terreno:
+
+1. Ler `PROJECT.md` (valor central, stack, receitas), `STATE.md` (feature ativa, bloqueios), `config.json` (próximo ID)
+2. Listar features existentes (frontmatter) — notar áreas cobertas, padrões de naming
+3. Se há features `draft`/`blocked`, mencionar — talvez retomar em vez de criar nova
+
+Resumo: `Projeto: X | Stack: Y | Features: N (X done, Y active) | Próxima: FEAT-NNN`
+
+### Fase 1 — Entender a Feature
+
+O objetivo é sair desta fase com entendimento completo do que construir. Conversar com o usuário até ter clareza — pode ser uma mensagem ou várias.
+
+1. **Título** — curto e descritivo, identifica a feature de relance
+2. **Problema** — qual dor ou necessidade motiva essa feature? Por que importa agora?
+3. **Visão** — o que entrega e como o usuário se beneficia quando estiver pronta
+4. **Fluxo do usuário** — passos concretos que o usuário percorre do início ao fim
+5. **Requisitos** — testáveis, com critério claro de pass/fail. Perguntar: "como sei que está funcionando?"
+6. **Fora do escopo** — o que explicitamente NÃO faz parte. Perguntar: "tem algo parecido que não devemos incluir?"
+7. **Riscos/incertezas** — integração externa, tech nova, performance, dependência de terceiros
+8. **Receitas** — Se o PROJECT.md contiver receitas, consultar e sugerir as relevantes (ex: feature com formulário → React Hook Form + Zod). Se não houver, pular
+
+### Fase 2 — Propor Abordagens
+
+Propor 2-3 abordagens com trade-offs quando relevante. Recomendar uma com razão concreta. Pular se feature é simples/óbvia.
+
+### Fase 3 — Decompor em Fases
+
+Seguir estrutura de `TPL-FEATURE.md` (seção "Implementação"). Para definições de status e ciclo de vida, ver `/hefesto-context`.
+
+#### Risk-first ordering
+
+Incerteza primeiro — invalidar premissas cedo. Se sem risco, ordenar por dependência natural.
+
+#### Rastreabilidade REQ→Fase
+
+Cada fase lista quais REQ-NN cobre. Verificar cobertura total — alertar se algum REQ ficou órfão.
+
+Cada fase atômica (~30 min).
+
+### Fase 4 — Detectar Escopo Excessivo
+
+Se > 5 fases ou > 10 requisitos: alertar e sugerir divisão concreta. Advisory, não mandatório.
+
+### Fase 5 — Self-Review
+
+- [ ] Título claro (não genérico)
+- [ ] Visão inclui O QUE e POR QUÊ
+- [ ] Pelo menos 2 requisitos testáveis
+- [ ] "Fora do Escopo" preenchido
+- [ ] Fases atômicas com critérios de aceitação
+
+Se falhar, pedir complemento. Se usuário disser "segue assim", respeitar.
+
+### Fase 6 — Criar Arquivo
 
-Seguido pelas seções: Visão, Fluxo do Usuário, Requisitos, Fora do Escopo, Implementação (com Fases), Notas Técnicas.
+1. Gerar ID `FEAT-NNN` (counter + 1, zero-padded) e slug (lowercase, hifenizado, max 40 chars, sem acentos)
+2. Ler `.hefesto/templates/TPL-FEATURE.md` e criar `.hefesto/features/FEAT-NNN-slug.md` substituindo placeholders
+3. Atualizar `config.json` (feature.counter)
+4. Atualizar tabela de Features em `PROJECT.md`
+5. Atualizar `STATE.md` se for primeira feature ou nenhuma ativa
+6. Seletor: "Promover para `ready` ou continuar iterando?"
+   - Se **ready**: atualizar status e STATE.md
+   - Se **iterar**: coletar ajustes, aplicar, repetir até promoção ou encerramento
+7. Sugerir `/hefesto-execute` quando pronto

package/skills/hefesto-security/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: hefesto-security
+description: >
+  Revisão de segurança de código. Encontra vulnerabilidades e aplica fixes.
+  ATIVAR quando: "segurança", "security", "vulnerabilidade", "XSS", "injection", "OWASP",
+  "segredo exposto", "código seguro", "auditoria de segurança", "security review".
+  Também: padrões perigosos (eval, exec, deserialização), inputs não validados, falhas silenciosas.
+user-invocable: true
+disable-model-invocation: false
+argument-hint: '[arquivos ou escopo opcional]'
+---
+
+# Hefesto Security
+
+Revisão de segurança que encontra vulnerabilidades reais e aplica fixes concretos. Zero tolerância a falhas silenciosas e padrões perigosos.
+
+## Princípios
+
+1. **Falhas silenciosas são inaceitáveis** — catch vazio é bug escondido; todo erro deve ser logado
+2. **Validar nas bordas** — inputs de usuário, APIs externas, env vars. Dados internos entre módulos não precisam
+3. **Sem segredos em código** — API keys, tokens, passwords em variáveis de ambiente, nunca hardcoded
+
+## Workflow
+
+### Fase 1 — Identificar escopo
+
+1. Se argumentos fornecidos → usar esses arquivos
+2. Senão, buscar feature ativa:
+   - Ler `.hefesto/STATE.md` → extrair arquivos modificados do frontmatter
+   - Se STATE.md não existir ou não tiver arquivos → `git diff --name-only` (staged + unstaged)
+3. Fallback → `git diff --name-only HEAD~1`
+4. Filtrar apenas código-fonte (excluir binários, lock files, build artifacts, código gerado)
+5. Excluir: diretórios de dependências, `dist/`, `build/`, `*.lock`, `*.lockb`, arquivos auto-gerados
+
+### Fase 2 — Análise de vulnerabilidades
+
+Ler `references/severity-and-judgment.md` — usar critérios de severidade e regras de falso positivo ao longo de toda a análise. Ler `references/boundaries-and-bypasses.md` — verificar cada boundary type aplicável.
+
+Para cada arquivo no escopo, analisar semanticamente estas categorias universais:
+
+1. **Code injection** — eval, exec, desserialização insegura, template injection, dynamic imports — em qualquer linguagem
+2. **Data injection** — SQL, NoSQL, LDAP, command injection, XSS — em qualquer framework ou ORM
+3. **Input validation gaps** — dados cruzando trust boundaries sem validação (consultar boundaries reference)
+4. **Auth & access control** — rotas sem auth, IDOR, CORS permissivo, CSRF, missing role checks
+5. **Insecure configuration** — debug mode em produção, headers de segurança ausentes, crypto fraco, default credentials
+6. **Data exposure** — dados sensíveis em logs, responses, URLs, query params, error messages
+7. **Resource exhaustion** — queries sem limit, missing pagination, missing timeouts, body size ilimitado
+
+Para cada finding, avaliar contexto antes de reportar — consultar "When NOT to Report" na referencia de severidade.
+
+### Fase 3 — Falhas silenciosas
+
+Ler `references/severity-and-judgment.md` seção "Silent Failures" — contém as 6 categorias universais, critérios de classificação e exceções.
+
+1. Encontrar todos os construtos de error handling na(s) linguagem(ns) detectada(s)
+2. Classificar cada um usando as categorias e critérios da referência
+3. Consultar "Quando silenciamento é aceitável" antes de reportar
+
+### Fase 4 — Segredos
+
+Ler `references/secrets-detection.md`.
+
+1. Usar regex por provider e genericos para grep nos arquivos do escopo
+2. Consultar "Exceptions" em `references/severity-and-judgment.md` antes de reportar — nem todo match e secret real
+3. Verificar `.gitignore` conforme "Gitignore Audit"
+4. Verificar se `.env` esta committed no git
+
+### Fase 5 — Aplicar correções
+
+1. Para issues **🔴 critical**: aplicar fix automaticamente
+   - Gerar correção apropriada para a linguagem/framework detectado
+   - Erros engolidos → adicionar log + re-throw ou return adequado
+   - Code injection → substituir por alternativa segura
+   - Segredos hardcoded → mover para variável de ambiente
+   - Queries com interpolação → parameterized queries
+
+2. Para issues **⚠ warning**: aplicar fix se a correção é clara e segura. Para mudanças que alteram comportamento (ex: adicionar validação que pode rejeitar inputs), perguntar antes
+
+3. Rodar verification commands após fixes para garantir que nada quebrou
+
+4. Apresentar relatório no formato `TPL-SECURITY.md` — preencher todas as seções aplicáveis, omitir seções sem issues
+
+## Notas
+
+- Se o projeto não tiver `.hefesto/`, o skill funciona com `git diff` e `CLAUDE.md`
+- Não reportar vulnerabilidades em dependências (escopo de ferramentas de audit de dependências)
+- Não reportar issues em código gerado
+- Priorizar issues com impacto real sobre issues teóricas
+- Se invocado pelo `/hefesto-execute`, o relatório é passado para o Argos junto com o resultado da feature

package/skills/hefesto-security/references/boundaries-and-bypasses.md

@@ -0,0 +1,152 @@
+# Boundaries e Bypass Techniques
+
+Trust boundaries universais e tecnicas de bypass de validacao. Independente de linguagem ou framework.
+
+## Quick Index
+
+- **Tipos de boundary** → "Boundaries" (linha 12)
+- **Tecnicas de bypass** → "Bypass Vectors" (linha 72)
+- **Como detectar** → "How to Detect" (linha 117)
+
+---
+
+## Boundaries
+
+### Form inputs / JSON body
+
+Dados submetidos via form HTML ou JSON body em POST/PUT/PATCH.
+
+| O que verificar                 | Quando e problema                                    |
+| ------------------------------- | ---------------------------------------------------- |
+| Usado diretamente em DB query   | Sempre                                               |
+| Usado em operacao de filesystem | Sempre                                               |
+| Usado em redirect               | Sempre                                               |
+| Tipos nao verificados           | Se vem de JSON body (pode ser string, array, objeto) |
+| Tamanho nao limitado            | Se e string longa — DoS via payload gigante          |
+
+### Query params / route params
+
+Dados na URL: `/users/:id?sort=name&order=asc`.
+
+| O que verificar                      | Quando e problema             |
+| ------------------------------------ | ----------------------------- |
+| Param numerico sem validacao de tipo | Sempre                        |
+| Param usado em regex                 | Sempre — ReDoS                |
+| Param usado em path de filesystem    | Sempre — path traversal       |
+| Sort/order sem whitelist             | Se usado em query — injection |
+| Pagination sem limites               | Se usado em LIMIT — DoS       |
+
+### Respostas de API externa
+
+Dados retornados por APIs de terceiros. Nao confiar mesmo em APIs "de confianca".
+
+| O que verificar                | Quando e problema                     |
+| ------------------------------ | ------------------------------------- |
+| Estrutura nao validada         | Sempre — crash se estrutura mudou     |
+| Dados renderizados no frontend | Se contem HTML/JS — XSS stored        |
+| Status code nao verificado     | Se assume sucesso                     |
+| Dados usados em query          | Sempre — injection via dados externos |
+
+### Headers / Cookies
+
+| O que verificar                               | Quando e problema                                        |
+| --------------------------------------------- | -------------------------------------------------------- |
+| Cookie usado sem validacao                    | Se contem dados de sessao (JWT sem verificar assinatura) |
+| Header Host / X-Forwarded-For usado em logica | Sempre — spoofavel                                       |
+| Content-Type nao verificado                   | Se processa body condicionalmente                        |
+| Referer / Origin para autenticacao            | Sempre — spoofavel                                       |
+
+### File uploads
+
+| O que verificar                        | Quando e problema                       |
+| -------------------------------------- | --------------------------------------- |
+| Tipo nao validado (MIME + magic bytes) | Sempre                                  |
+| Tamanho nao limitado                   | Sempre — DoS                            |
+| Nome do arquivo nao sanitizado         | Se usado no filesystem — path traversal |
+| Conteudo nao escaneado                 | Se armazenado/servido — polyglot files  |
+| Extensao dupla                         | Se whitelist por extensao — bypass      |
+
+### Boundaries adicionais
+
+| Boundary                         | O que verificar                                                                          |
+| -------------------------------- | ---------------------------------------------------------------------------------------- |
+| **WebSocket messages**           | Cada mensagem deve ser validada — nao ha "sessao validada" que garanta mensagens futuras |
+| **GraphQL inputs**               | Validar args de cada resolver. Queries aninhadas → DoS (query depth limiting)            |
+| **CLI args**                     | Validar antes de usar em shell commands, file operations, ou regex                       |
+| **Variaveis de ambiente**        | Validar formato esperado no startup (URL valida, numero, enum)                           |
+| **IPC / inter-process**          | Mensagens entre processos devem ser validadas — outro processo pode ser comprometido     |
+| **Database read-back**           | Dados lidos do DB podem ter sido inseridos sem sanitizacao em versao anterior do codigo  |
+| **gRPC / RPC inputs**            | Mesmo com tipos definidos no proto, validar ranges e constraints de negocio              |
+| **Event queue / message broker** | Mensagens de filas (Kafka, RabbitMQ, SQS) sao tao untrusted quanto HTTP requests         |
+
+---
+
+## Bypass Vectors
+
+Tecnicas que atacantes usam para contornar validacao fraca. Verificar se a validacao cobre estes cenarios:
+
+### Type coercion
+
+Input esperado num tipo, recebido em outro. Comparacoes fracas (`==` vs `===`), conversoes implicitas, e frameworks que aceitam tipos variados para o mesmo parametro (string se 1 valor, array se multiplos).
+
+**Deteccao**: comparacao fraca de input com valor fixo; ausencia de type check explicito.
+
+### Prototype / object pollution
+
+Payload JSON com propriedades especiais (`__proto__`, `constructor.prototype`) que injetam propriedades em objetos. Afeta linguagens com heranca prototipal ou merge recursivo de objetos.
+
+**Deteccao**: JSON parse seguido de merge/assign/spread sem filtrar keys especiais.
+
+### Unicode normalization
+
+Caracteres Unicode que normalizam para equivalentes ASCII. Pode bypassar blacklists de filename, filtros de input, e comparacoes de string.
+
+**Deteccao**: validacao de filename ou input sem normalizacao previa; filtros baseados em comparacao byte-a-byte.
+
+### Null byte injection
+
+Null bytes (`\0`, `\x00`, `%00`) que truncam strings em sistemas baseados em C. Path traversal classico: `../../etc/passwd\0.png` — extensao ignorada.
+
+**Deteccao**: input usado em operacoes de filesystem sem filtrar null bytes.
+
+### Array vs scalar ambiguity
+
+Parametros que podem ser string ou array dependendo de quantos valores sao enviados. Frameworks web frequentemente tem este comportamento em query params.
+
+**Deteccao**: input de query params usado sem type check ou conversao explicita.
+
+---
+
+## How to Detect
+
+Heuristicas para identificar "input → operacao sem validacao no meio":
+
+### 1. Rastrear fluxo de dados
+
+```
+input source → variavel local → operacao perigosa
+```
+
+Se entre a origem (request, CLI arg, env var, file upload, API response) e o destino (DB query, filesystem op, shell command, redirect, HTML render) nao ha:
+
+- Schema validation (qualquer biblioteca de validacao)
+- Type assertion / type guard
+- Sanitizacao explicita
+- Parameterized query / prepared statement
+
+→ Reportar como ⚠ warning.
+
+### 2. Sinais de validacao ausente
+
+- Input de request usado na mesma funcao que operacao perigosa sem chamada de validacao entre eles
+- Dados de API externa usados diretamente sem schema validation
+- Parametros de rota usados em query sem conversao de tipo
+
+### 3. Sinais de validacao presente
+
+- Import de biblioteca de validacao no arquivo
+- Schema definido antes do handler
+- Middleware de validacao na rota
+- Type guards explicitos
+- Parameterized queries (placeholders em vez de interpolacao)
+- Sanitization functions entre input e uso