wizz-method 2.2.0 → 2.3.1

package/src/skills-lib/wizz-web-security/references/headers-rate-limit-cors.md

@@ -1,10 +1,10 @@
-# Headers de Segurança, Rate Limiting, CORS, e Vazamento de Dados
+# Security Headers, Rate Limiting, CORS, and Data Leakage
 
-Carregue este arquivo ao implementar/revisar headers de segurança, rate limiting, CORS, ou o formato de resposta de uma API (over-fetch/PII).
+Load this file when implementing/reviewing security headers, rate limiting, CORS, or an API's response shape (over-fetch/PII).
 
-## Headers de segurança obrigatórios
+## Mandatory security headers
 
-`X-Frame-Options: DENY` + `frame-ancestors 'none'` no CSP mata **clickjacking** (o site não pode ser embutido em `<iframe>` de outro domínio). Fix de 1 minuto, sempre presente.
+`X-Frame-Options: DENY` + `frame-ancestors 'none'` in the CSP kills **clickjacking** (the site can't be embedded in an `<iframe>` from another domain). A 1-minute fix, always present.
 
 ```
 Content-Security-Policy: default-src 'self'; frame-ancestors 'none'
@@ -15,7 +15,7 @@ Referrer-Policy: strict-origin-when-cross-origin
 Permissions-Policy: camera=(), microphone=(), geolocation=()
 ```
 
-Como adicionar em Next.js (`next.config.ts`):
+How to add it in Next.js (`next.config.ts`):
 ```ts
 async headers() {
   return [
@@ -44,46 +44,46 @@ async headers() {
 },
 ```
 
-> **Cuidado:** CSP errada quebra o app. Teste sempre em dev antes de subir. Ajuste os domínios (`script-src`, `connect-src`) conforme os serviços reais do projeto.
+> **Careful:** a wrong CSP breaks the app. Always test in dev before deploying. Adjust the domains (`script-src`, `connect-src`) to the project's real services.
 
 ## Rate Limiting
-- Login: limite por IP **e** por conta (só por IP não segura brute force distribuído; só por conta não segura scan de vários e-mails)
-- APIs públicas: limite por IP e por token
-- Endpoints de reset de senha: especialmente restritivos
-- Endpoints de cobrança (checkout, portal): sempre com rate limit
-- Next.js: `@upstash/ratelimit` no route handler, ou WAF da Vercel para regras por rota
-- Fail closed: se o backend do rate limit cair (ex: Redis fora), rotas de escrita devem negar a request, não deixar passar
-- Comparações de token/secret: `crypto.timingSafeEqual`, nunca `!==` (detalhe em wizz-auth-and-secrets)
-- Sem rate limit = brute force de graça. Somar lockout/CAPTCHA após N falhas no login
+- Login: limit per IP **and** per account (IP-only doesn't protect against distributed brute force; account-only doesn't protect against scanning many emails)
+- Public APIs: limit per IP and per token
+- Password reset endpoints: especially restrictive
+- Billing endpoints (checkout, portal): always with rate limiting
+- Next.js: `@upstash/ratelimit` in the route handler, or Vercel's WAF for per-route rules
+- Fail closed: if the rate-limit backend goes down (e.g. Redis is out), write routes should deny the request, not let it through
+- Token/secret comparisons: `crypto.timingSafeEqual`, never `!==` (details in wizz-auth-and-secrets)
+- No rate limit = free brute force. Add lockout/CAPTCHA after N failed login attempts
 
-### Origem do IP atrás de proxy/CDN
-Se o app roda atrás de Vercel/Cloudflare/qualquer proxy, o IP do socket é o do proxy, não o do cliente. Ler o socket direto faz **o mundo inteiro contar como um IP só** e o rate limit deixa de existir na prática.
-- Vercel: use `x-forwarded-for` (ou `req.ip` no runtime que já resolve). Pegue o **primeiro** IP da lista, mas só confie na cadeia que vem do seu proxy.
-- Nunca confie em `x-forwarded-for` cru vindo de origem não-proxy (o cliente falsifica o header). Configure a lib de rate limit para o número certo de proxies à frente.
+### IP origin behind a proxy/CDN
+If the app runs behind Vercel/Cloudflare/any proxy, the socket's IP is the proxy's, not the client's. Reading the raw socket makes **the entire world count as a single IP** and the rate limit effectively stops existing.
+- Vercel: use `x-forwarded-for` (or `req.ip` in the runtime that already resolves it). Take the **first** IP in the list, but only trust the chain that comes from your own proxy.
+- Never trust a raw `x-forwarded-for` coming from a non-proxy origin (the client can spoof the header). Configure the rate-limit library for the correct number of proxies in front.
 
-### Custo por chamada (rota que gasta dinheiro real)
-Toda rota que chama modelo de linguagem, dispara SMS, envia e-mail, processa arquivo ou bate em API paga de terceiro precisa de rate limit **e** quota por conta. Rota de agente de IA exposta sem limitador é crítica mesmo sem vazar dado nenhum: 10.000 chamadas em loop viram conta de centenas a milhares de reais/dólares. Estime o custo unitário e multiplique por 10k ao avaliar a rota.
+### Per-call cost (a route that spends real money)
+Every route that calls a language model, sends an SMS, sends an email, processes a file, or hits a paid third-party API needs rate limiting **and** a per-account quota. An AI agent route exposed without a limiter is critical even without leaking any data at all: 10,000 calls in a loop turn into a bill of hundreds to thousands of dollars. Estimate the unit cost and multiply by 10k when assessing the route.
 
-### Extração por paginação
-Rota que devolve um registro por vez e, chamada em sequência, entrega a base inteira. Barre com: filtro por dono na query (o mesmo do IDOR), limite máximo de página, e detecção de varredura (muitos ids sequenciais do mesmo cliente).
+### Extraction via pagination
+A route that returns one record at a time and, called in sequence, hands over the entire database. Block it with: an owner filter in the query (the same as for IDOR), a maximum page size, and scan detection (many sequential IDs from the same client).
 
 ## CORS
-- **Nunca reflita o header `Origin` recebido** de volta em `Access-Control-Allow-Origin` (isso libera qualquer site a chamar sua API com credenciais)
-- Use uma **allowlist explícita** de origens: compare o `Origin` recebido contra a lista e só então ecoe o valor exato daquela origem
-- `Access-Control-Allow-Credentials: true` NUNCA junto de `Access-Control-Allow-Origin: *`
-- Padrão = negar: origem desconhecida → sem headers CORS (o browser bloqueia sozinho)
+- **Never reflect the received `Origin` header** back in `Access-Control-Allow-Origin` (this lets any site call your API with credentials)
+- Use an explicit **allowlist** of origins: compare the received `Origin` against the list and only then echo back that exact origin's value
+- `Access-Control-Allow-Credentials: true` NEVER together with `Access-Control-Allow-Origin: *`
+- Default = deny: unknown origin → no CORS headers (the browser blocks it on its own)
 ```ts
 const ALLOWED = new Set(["https://app.exemplo.com", "https://exemplo.com"])
 const origin = req.headers.get("origin")
 if (origin && ALLOWED.has(origin)) {
-  res.headers.set("Access-Control-Allow-Origin", origin) // valor exato, nunca "*" com credentials
+  res.headers.set("Access-Control-Allow-Origin", origin) // exact value, never "*" with credentials
   res.headers.set("Vary", "Origin")
 }
 ```
 
-## Vazamento de dados na resposta (over-fetch / PII)
-- Retorne **só os campos que a tela precisa**: monte um DTO/allowlist de saída, nunca devolva a row inteira do banco
-- NUNCA inclua `password`, `password_hash`, tokens, secrets ou colunas internas na resposta de API (é a falha mais grave da lista de PII)
-- Supabase: `.select('id, name, email')` explícito, nunca `.select('*')` em endpoint que responde ao cliente
-- Objeto do usuário logado: serialize por um mapper que só expõe campos públicos
-- Erros: não vaze stack trace, SQL nem nome de tabela pro cliente. Mensagem genérica no response, detalhe só no log do servidor
+## Data leakage in the response (over-fetch / PII)
+- Return **only the fields the screen needs**: build an output DTO/allowlist, never return the whole database row
+- NEVER include `password`, `password_hash`, tokens, secrets, or internal columns in an API response (this is the most serious failure on the PII list)
+- Supabase: explicit `.select('id, name, email')`, never `.select('*')` on an endpoint that responds to the client
+- Logged-in user object: serialize it through a mapper that only exposes public fields
+- Errors: don't leak stack traces, SQL, or table names to the client. Generic message in the response, detail only in the server log

package/src/skills-lib/wizz-web-security/references/owasp-top5-detalhado.md

@@ -1,14 +1,14 @@
-# OWASP — Detalhe das 5 categorias mais comuns
+# OWASP — Detail of the 5 most common categories
 
-Carregue este arquivo ao aprofundar numa das falhas do triage rápido (seções 1-5 referenciadas na tabela do SKILL.md).
+Load this file when digging deeper into one of the failures from the quick triage (sections 1-5 referenced in the SKILL.md table).
 
 ## 1. Broken Access Control
-- Verifique permissões no servidor, nunca apenas no frontend
-- IDOR (Insecure Direct Object Reference): valide se o usuário tem acesso ao recurso pelo ID
-- Princípio do menor privilégio em todas as rotas
-- Next.js: middleware não é a única barreira. Re-verifique auth dentro do route handler, Server Action ou página (bypass de middleware já teve CVE)
+- Check permissions on the server, never only on the frontend
+- IDOR (Insecure Direct Object Reference): validate that the user has access to the resource by ID
+- Principle of least privilege on every route
+- Next.js: middleware isn't the only barrier. Re-check auth inside the route handler, Server Action, or page (a middleware bypass has already had a CVE)
 
-Exemplo anti-IDOR (Next.js + Clerk + Supabase):
+Anti-IDOR example (Next.js + Clerk + Supabase):
 ```ts
 // app/api/projects/[id]/route.ts
 import { auth } from "@clerk/nextjs/server"
@@ -21,63 +21,63 @@ export async function GET(req: Request, { params }: { params: Promise<{ id: stri
     .from("projects")
     .select("id, name")
     .eq("id", id)
-    .eq("user_id", userId) // posse verificada na query, além do RLS
+    .eq("user_id", userId) // ownership verified in the query, in addition to RLS
     .single()
-  if (!data) return new Response("Not found", { status: 404 }) // 404, não 403 (não confirma que o recurso existe)
+  if (!data) return new Response("Not found", { status: 404 }) // 404, not 403 (doesn't confirm the resource exists)
   return Response.json(data)
 }
 ```
 
-### RLS: policy permissiva é pior que policy nenhuma
-Ler os arquivos de migration/policy versionados e checar:
-- Toda tabela de domínio tem `ENABLE ROW LEVEL SECURITY`?
-- Nenhuma policy é permissiva: `USING (true)` ou `WITH CHECK (true)` libera geral, mas o painel do Supabase mostra a trava como "ativa". Amarre sempre ao dono: `USING (auth.uid() = user_id)`.
-- Tabela criada em migration recente **sem** policy correspondente = exposta.
+### RLS: a permissive policy is worse than no policy
+Read the versioned migration/policy files and check:
+- Does every domain table have `ENABLE ROW LEVEL SECURITY`?
+- Is no policy permissive: `USING (true)` or `WITH CHECK (true)` opens it to everyone, but the Supabase dashboard shows the lock as "active." Always tie it to the owner: `USING (auth.uid() = user_id)`.
+- A table created in a recent migration **without** a corresponding policy = exposed.
 
 ```sql
--- ERRADO: mostra RLS ativo no painel, mas libera qualquer um
+-- WRONG: shows RLS active in the dashboard, but opens it to anyone
 create policy "read" on projects for select using (true);
 
--- CERTO: amarra o dono
+-- RIGHT: ties it to the owner
 alter table projects enable row level security;
 create policy "own rows" on projects
   for select using (auth.uid() = user_id);
 ```
 
-> RLS de verdade é estado do banco, não arquivo. O que está no repo é ponto de partida: confirme o estado real no dashboard/`\d+` do Postgres.
+> Real RLS is database state, not a file. What's in the repo is a starting point: confirm the real state in the dashboard/`\d+` of Postgres.
 
-## 6. Mass Assignment (atribuição em massa)
-O corpo da requisição inteiro repassado para o banco (`spread` do objeto, `update`/`create` com o payload completo) deixa o atacante setar qualquer coluna, mesmo as que não estão no formulário. Alvos clássicos: `role`, `is_admin`, `plan`, `balance`, `payment_status`, `user_id`/`owner_id`.
+## 6. Mass Assignment
+Passing the entire request body through to the database (`spread` of the object, `update`/`create` with the full payload) lets an attacker set any column, even ones not in the form. Classic targets: `role`, `is_admin`, `plan`, `balance`, `payment_status`, `user_id`/`owner_id`.
 
 ```ts
-// ERRADO: o cliente manda { name: "x", role: "admin" } e vira admin
+// WRONG: the client sends { name: "x", role: "admin" } and becomes admin
 await supabase.from("users").update({ ...body }).eq("id", userId)
 
-// CERTO: allowlist explícita, só os campos do formulário
-const { name, bio } = updateSchema.parse(body) // Zod com só os campos permitidos
+// RIGHT: explicit allowlist, only the form's fields
+const { name, bio } = updateSchema.parse(body) // Zod with only the allowed fields
 await supabase.from("users").update({ name, bio }).eq("id", userId)
 ```
 
-Regra: **nunca** `...body` / `...req.body` num write. Sempre desestruture (ou valide com um schema que só contém os campos editáveis). Campos de papel, permissão, plano, saldo, status de pagamento e id de dono nunca vêm do cliente.
+Rule: **never** `...body` / `...req.body` in a write. Always destructure (or validate with a schema that only contains the editable fields). Role, permission, plan, balance, payment status, and owner id fields never come from the client.
 
 ## 2. Cryptographic Failures
-- HTTPS em tudo, sem exceção
-- HSTS header com includeSubDomains
-- Não exponha dados sensíveis em URLs (query strings ficam em logs)
+- HTTPS everywhere, no exceptions
+- HSTS header with includeSubDomains
+- Don't expose sensitive data in URLs (query strings end up in logs)
 
 ## 3. Injection
-- SQL: queries parametrizadas sempre
+- SQL: always parameterized queries
 - XSS: sanitize outputs, use Content-Security-Policy
-- Command injection: nunca execute input do usuário como comando shell
+- Command injection: never execute user input as a shell command
 
 ## 4. Cross-Site Scripting (XSS)
-- Escape HTML em todo output de dado do usuário
-- React/Next.js escapa JSX por padrão. O risco real está em `dangerouslySetInnerHTML`: sanitize antes com DOMPurify (ou não use)
-- URLs vindas do usuário em `href`/`src`: bloqueie esquemas `javascript:` e `data:` (valide que começa com `https://` ou caminho relativo)
-- Content-Security-Policy: bloqueie inline scripts
-- HttpOnly e Secure flags nos cookies de sessão
+- Escape HTML on every piece of user-generated output
+- React/Next.js escapes JSX by default. The real risk is in `dangerouslySetInnerHTML`: sanitize with DOMPurify first (or don't use it)
+- User-supplied URLs in `href`/`src`: block `javascript:` and `data:` schemes (validate that it starts with `https://` or a relative path)
+- Content-Security-Policy: block inline scripts
+- HttpOnly and Secure flags on session cookies
 
 ## 5. CSRF
-- SameSite=Strict ou Lax nos cookies de sessão
-- CSRF token em formulários state-changing
-- Verifique Origin/Referer em requests sensíveis
+- SameSite=Strict or Lax on session cookies
+- CSRF token on state-changing forms
+- Check Origin/Referer on sensitive requests

package/tools/hooks/session-rules.js

@@ -4,9 +4,9 @@
 //
 // Três responsabilidades, um processo só (SessionStart roda 1x por sessão):
 //
-//   1. Regras de comunicação, injetadas UMA vez por sessão (antes:
-//      no-narration-enforce repetia ~80 tokens em TODO prompt via
-//      UserPromptSubmit). Mesmo conteúdo, custo fixo por sessão.
+//   1. Communication rules, injected ONCE per session (before: no-narration-enforce
+//      repeated ~80 tokens on EVERY prompt via UserPromptSubmit). Same content,
+//      fixed cost per session.
 //
 //   2. Feature ativa: resolve o `active_feature` SOZINHO, sem o usuário
 //      precisar invocar `wizz-set-feature` e responder duas perguntas. Ordem:
@@ -26,15 +26,18 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 
-// Cópia comprimida e INTENCIONAL da regra de comunicação. A fonte é
-// src/modules/wizz/_shared/communication-rules.md; este hook precisa ser
-// autocontido porque roda de ~/.claude/hooks, longe do repo. Editou lá,
-// edite aqui: test/test-feature-context.js falha se as duas divergirem.
+// Compressed and INTENTIONAL copy of the communication rule. The source is
+// src/modules/wizz/_shared/communication-rules.md; this hook needs to be
+// self-contained because it runs from ~/.claude/hooks, far from the repo. Edit
+// it there, edit it here too: test/test-feature-context.js fails if the two diverge.
 const RULES =
-  'REGRA DE COMUNICAÇÃO (permanente, não-negociável): não narrar o passo a passo ' +
-  'enquanto trabalha; pausar e perguntar SÓ em decisão do usuário ou risco ' +
-  'irreversível; fechar SEMPRE com resumo curto em tópicos, linguagem simples, ' +
-  'sem jargão; sem em-dashes; comunicação enxuta por default, expandir só sob demanda.';
+  'COMMUNICATION RULE (permanent, non-negotiable): do not narrate the step-by-step ' +
+  'while working; pause and ask ONLY for a user decision or irreversible risk; ' +
+  'always close with a short summary in bullet points, plain language, no jargon; ' +
+  'no em-dashes only in text a third party reads (public page, copy, UI), ' +
+  'code comments, commits, and internal notes are exempt from this check; ' +
+  'concise communication by default, expand only on request; ' +
+  'reply to the user in the language chosen at install (communication_language).';
 
 // Branches que NUNCA viram feature: são linha principal, não trabalho nomeado.
 const TRUNK = new Set(['main', 'master', 'develop', 'dev', 'staging', 'stage', 'prod', 'production', 'trunk', 'default', 'release']);