wizz-method 1.4.0 → 1.5.0

package/src/skills-lib/ui-ux-pro-max/references/workflow-guide.md

@@ -0,0 +1,157 @@
+# Full Workflow Guide
+
+Load this file when actually building or reviewing a UI and you need the complete step-by-step procedure (not just the first command).
+
+## Prerequisites
+
+Check if Python is installed:
+
+```bash
+python3 --version || python --version
+```
+
+If Python is not installed, install it based on user's OS:
+
+**macOS:**
+```bash
+brew install python3
+```
+
+**Ubuntu/Debian:**
+```bash
+sudo apt update && sudo apt install python3
+```
+
+**Windows:**
+```powershell
+winget install Python.Python.3.12
+```
+
+## How to Use This Skill
+
+When user requests UI/UX work (design, build, create, implement, review, fix, improve), follow this workflow:
+
+### Step 1: Analyze User Requirements
+
+Extract key information from user request:
+- **Product type**: SaaS, e-commerce, portfolio, dashboard, landing page, etc.
+- **Style keywords**: minimal, playful, professional, elegant, dark mode, etc.
+- **Industry**: healthcare, fintech, gaming, education, etc.
+- **Stack**: React, Vue, Next.js, or default to `html-tailwind`
+
+### Step 2: Generate Design System (REQUIRED)
+
+**Always start with `--design-system`** to get comprehensive recommendations with reasoning:
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "<product_type> <industry> <keywords>" --design-system [-p "Project Name"]
+```
+
+This command:
+1. Searches 5 domains in parallel (product, style, color, landing, typography)
+2. Applies reasoning rules from `ui-reasoning.csv` to select best matches
+3. Returns complete design system: pattern, style, colors, typography, effects
+4. Includes anti-patterns to avoid
+
+**Example:**
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "beauty spa wellness service" --design-system -p "Serenity Spa"
+```
+
+### Step 2b: Persist Design System (Master + Overrides Pattern)
+
+To save the design system for hierarchical retrieval across sessions, add `--persist`:
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "<query>" --design-system --persist -p "Project Name"
+```
+
+This creates:
+- `design-system/MASTER.md` — Global Source of Truth with all design rules
+- `design-system/pages/` — Folder for page-specific overrides
+
+**With page-specific override:**
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "<query>" --design-system --persist -p "Project Name" --page "dashboard"
+```
+
+This also creates:
+- `design-system/pages/dashboard.md` — Page-specific deviations from Master
+
+**How hierarchical retrieval works:**
+1. When building a specific page (e.g., "Checkout"), first check `design-system/pages/checkout.md`
+2. If the page file exists, its rules **override** the Master file
+3. If not, use `design-system/MASTER.md` exclusively
+
+### Step 3: Supplement with Detailed Searches (as needed)
+
+After getting the design system, use domain searches to get additional details:
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "<keyword>" --domain <domain> [-n <max_results>]
+```
+
+**When to use detailed searches:**
+
+| Need | Domain | Example |
+|------|--------|---------|
+| More style options | `style` | `--domain style "glassmorphism dark"` |
+| Chart recommendations | `chart` | `--domain chart "real-time dashboard"` |
+| UX best practices | `ux` | `--domain ux "animation accessibility"` |
+| Alternative fonts | `typography` | `--domain typography "elegant luxury"` |
+| Landing structure | `landing` | `--domain landing "hero social-proof"` |
+
+### Step 4: Stack Guidelines (Default: html-tailwind)
+
+Get implementation-specific best practices. If user doesn't specify a stack, **default to `html-tailwind`**.
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "<keyword>" --stack html-tailwind
+```
+
+Available stacks: `html-tailwind`, `react`, `nextjs`, `vue`, `svelte`, `swiftui`, `react-native`, `flutter`, `shadcn`, `jetpack-compose`
+
+## Example Workflow
+
+**User request:** "Làm landing page cho dịch vụ chăm sóc da chuyên nghiệp"
+
+### Step 1: Analyze Requirements
+- Product type: Beauty/Spa service
+- Style keywords: elegant, professional, soft
+- Industry: Beauty/Wellness
+- Stack: html-tailwind (default)
+
+### Step 2: Generate Design System (REQUIRED)
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "beauty spa wellness service elegant" --design-system -p "Serenity Spa"
+```
+
+**Output:** Complete design system with pattern, style, colors, typography, effects, and anti-patterns.
+
+### Step 3: Supplement with Detailed Searches (as needed)
+
+```bash
+# Get UX guidelines for animation and accessibility
+python3 skills/ui-ux-pro-max/scripts/search.py "animation accessibility" --domain ux
+
+# Get alternative typography options if needed
+python3 skills/ui-ux-pro-max/scripts/search.py "elegant luxury serif" --domain typography
+```
+
+### Step 4: Stack Guidelines
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "layout responsive form" --stack html-tailwind
+```
+
+**Then:** Synthesize design system + detailed searches and implement the design.
+
+## Tips for Better Results
+
+1. **Be specific with keywords** - "healthcare SaaS dashboard" > "app"
+2. **Search multiple times** - Different keywords reveal different insights
+3. **Combine domains** - Style + Typography + Color = Complete design system
+4. **Always check UX** - Search "animation", "z-index", "accessibility" for common issues
+5. **Use stack flag** - Get implementation-specific best practices
+6. **Iterate** - If first search doesn't match, try different keywords

package/src/skills-lib/web-security/SKILL.md

@@ -11,175 +11,26 @@ description: >
 
 ## Falhas recorrentes em pentest (rankeadas por severidade)
 
-As que mais aparecem numa auditoria, com a correção direta. Use como triagem rápida.
+As que mais aparecem numa auditoria, com a correção direta. Use como triagem rápida — comece por aqui em toda revisão de segurança.
 
 | # | Falha | Severidade | Correção | Onde |
 |---|-------|-----------|----------|------|
-| 1 | SQL Injection | 🔴 Crítica (parada de linha) | Query parametrizada / query-builder, nunca interpolar string | seção 3 |
-| 2 | IDOR (recurso por ID sem checar dono) | 🔴 Crítica (parada de linha) | Validar posse do recurso no servidor a cada request | seção 1 |
-| 3 | Rate limit ausente (brute force grátis) | 🟠 Alta | Limite por IP **e** por conta + lockout/CAPTCHA no login | Rate Limiting |
-| 4 | CORS refletindo o `Origin` | 🟠 Alta | Allowlist de origens, nunca ecoar o `Origin` recebido | CORS |
-| 5 | PII/dado demais na resposta (até hash de senha) | 🟠 Alta | Retornar só os campos necessários (allowlist de saída) | Vazamento na resposta |
-| 6 | JWT na URL / token vivo pós-logout | 🟠 Alta | Token no header `Authorization` + revogar no logout | auth-and-secrets |
-| 7 | Enumeração de usuário (erro revela se e-mail existe) | 🟡 Média | Mensagem genérica + resposta em tempo constante | auth-and-secrets |
-| 8 | Clickjacking (sem header) | 🟡 Média (1 min) | `X-Frame-Options: DENY` + CSP `frame-ancestors 'none'` | Headers |
+| 1 | SQL Injection | 🔴 Crítica (parada de linha) | Query parametrizada / query-builder, nunca interpolar string | `references/owasp-top5-detalhado.md` §3 |
+| 2 | IDOR (recurso por ID sem checar dono) | 🔴 Crítica (parada de linha) | Validar posse do recurso no servidor a cada request | `references/owasp-top5-detalhado.md` §1 |
+| 3 | Rate limit ausente (brute force grátis) | 🟠 Alta | Limite por IP **e** por conta + lockout/CAPTCHA no login | `references/headers-rate-limit-cors.md` |
+| 4 | CORS refletindo o `Origin` | 🟠 Alta | Allowlist de origens, nunca ecoar o `Origin` recebido | `references/headers-rate-limit-cors.md` |
+| 5 | PII/dado demais na resposta (até hash de senha) | 🟠 Alta | Retornar só os campos necessários (allowlist de saída) | `references/headers-rate-limit-cors.md` |
+| 6 | JWT na URL / token vivo pós-logout | 🟠 Alta | Token no header `Authorization` + revogar no logout | skill `auth-and-secrets` |
+| 7 | Enumeração de usuário (erro revela se e-mail existe) | 🟡 Média | Mensagem genérica + resposta em tempo constante | skill `auth-and-secrets` |
+| 8 | Clickjacking (sem header) | 🟡 Média (1 min) | `X-Frame-Options: DENY` + CSP `frame-ancestors 'none'` | `references/headers-rate-limit-cors.md` |
 
 > As duas primeiras (SQLi e IDOR) são **parada de linha**: apareceu, corrige antes de qualquer coisa.
 
-## 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
+## References (load on demand)
 
-## 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)
-
-## 3. Injection
-- SQL: queries parametrizadas sempre
-- XSS: sanitize outputs, use Content-Security-Policy
-- Command injection: nunca execute input do usuário como comando shell
-
-## 4. Cross-Site Scripting (XSS)
-- Escape HTML em todo output de dado do usuário
-- Content-Security-Policy: bloqueie inline scripts
-- HttpOnly e Secure flags nos cookies de sessão
-
-## 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
-
-## Headers de segurança obrigatórios
-
-`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.
-
-```
-Content-Security-Policy: default-src 'self'; frame-ancestors 'none'
-X-Frame-Options: DENY
-X-Content-Type-Options: nosniff
-Strict-Transport-Security: max-age=63072000; includeSubDomains; preload
-Referrer-Policy: strict-origin-when-cross-origin
-Permissions-Policy: camera=(), microphone=(), geolocation=()
-```
-
-Como adicionar em Next.js (`next.config.ts`):
-```ts
-async headers() {
-  return [
-    {
-      source: "/(.*)",
-      headers: [
-        { key: "X-Frame-Options", value: "DENY" },
-        { key: "X-Content-Type-Options", value: "nosniff" },
-        { key: "Referrer-Policy", value: "strict-origin-when-cross-origin" },
-        { key: "Strict-Transport-Security", value: "max-age=63072000; includeSubDomains; preload" },
-        { key: "Permissions-Policy", value: "camera=(), microphone=(), geolocation=()" },
-        {
-          key: "Content-Security-Policy",
-          value: [
-            "default-src 'self'",
-            "script-src 'self' 'unsafe-inline' https://js.clerk.dev https://js.stripe.com https://www.googletagmanager.com",
-            "connect-src 'self' https://*.supabase.co https://api.clerk.dev https://api.stripe.com",
-            "frame-src https://js.stripe.com https://hooks.stripe.com",
-            "img-src 'self' data: https:",
-            "style-src 'self' 'unsafe-inline'",
-          ].join("; "),
-        },
-      ],
-    },
-  ]
-},
-```
-
-> **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.
-
-## 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
-- Comparações de token/secret: use `crypto.timingSafeEqual` (nunca `!==`)
-- Sem rate limit = brute force de graça. Somar lockout/CAPTCHA após N falhas no login
-
-## 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)
-```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("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
-
----
-
-## Checklist das 8 vulnerabilidades mais comuns
-
-Usar como auditoria rápida antes de deploy ou revisão de segurança.
-
-### 1. HTTPS forçado
-- [ ] A plataforma força HTTPS? (Vercel: sim por padrão)
-- [ ] Header `Strict-Transport-Security` configurado explicitamente no código?
-- [ ] Nenhuma URL `http://` hardcoded em redirects ou fetch?
-
-### 2. Validação no servidor
-- [ ] Todo endpoint de API valida input com Zod (`.parse()` ou `.safeParse()`)?
-- [ ] `workspaceId`/`userId` validados como UUID antes de ir ao banco?
-- [ ] Regras de negócio re-validadas no backend (nunca confiar só no cliente)?
-- [ ] Supabase: RLS ativo nas tabelas? Queries sempre filtram por `workspace_id`/`user_id`?
-
-### 3. Senha do banco / secrets no código
-- [ ] Nenhum secret hardcoded em `.ts`/`.tsx`/`.js`?
-- [ ] `.env*` no `.gitignore`? (`git check-ignore -v .env.local`)
-- [ ] `.env.local` nunca aparece em `git log --all`?
-- [ ] Cripto usa chave de `process.env`, sem fallback de string?
-- [ ] Grep de segurança: `grep -r "sk_live\|sk_test\|service_role\|eyJ" src/` → vazio?
-
-### 4. Rate limiting na API
-- [ ] Endpoints de autenticação têm rate limit por IP?
-- [ ] Endpoints de cobrança (checkout, portal Stripe) têm rate limit?
-- [ ] Endpoints que disparam operações caras/externas têm rate limit?
-- [ ] Endpoints de admin têm rate limit + comparação timing-safe?
-- [ ] Rotas de escrita de estado usam `failOpen: false`?
-
-### 5. Content Security Policy
-- [ ] Header `Content-Security-Policy` configurado? (`next.config.ts` `headers()` ou middleware)
-- [ ] `X-Frame-Options: DENY` configurado?
-- [ ] `X-Content-Type-Options: nosniff` configurado?
-- [ ] CSP testada em dev sem erros no console?
-
-### 6. Upload sem verificação de tipo
-- [ ] Se há upload: verifica MIME type no servidor (não só no cliente)?
-- [ ] Limite de tamanho de arquivo imposto no servidor?
-- [ ] Extensões permitidas em allowlist (não blocklist)?
-- [ ] Se não há upload: confirmar que não há `<input type="file">` escondido?
-
-### 7. SQL injection na busca
-- [ ] Nenhuma query monta SQL com string interpolation/concatenação?
-- [ ] Supabase: todo acesso via query-builder (`.from().select().eq()`) ou RPC com params nomeados?
-- [ ] RPCs Postgres auditadas no dashboard: não usam `EXECUTE format(...)` com input do usuário?
-- [ ] Grep: `grep -r "\.sql\|raw(\|\.query(" src/` → revisar resultados?
-
-### 8. Backup automatizado
-- [ ] Plano Supabase tem PITR ou backup diário habilitado? (verificar no dashboard)
-- [ ] Retenção de backup documentada?
-- [ ] Existe runbook de restauração?
-- [ ] Credenciais de backup protegidas (não no repo)?
-
----
+- `references/owasp-top5-detalhado.md` — detalhe + exemplo de código (Next.js + Clerk + Supabase) para as 5 categorias OWASP mais comuns: Broken Access Control, Cryptographic Failures, Injection, XSS, CSRF. Carregar ao aprofundar numa falha específica da tabela acima.
+- `references/headers-rate-limit-cors.md` — headers de segurança obrigatórios (com config pronta para `next.config.ts`), rate limiting (login/API/cobrança, fail-closed), CORS (allowlist, exemplo de código), e como evitar vazamento de PII/over-fetch na resposta de API. Carregar ao implementar ou revisar qualquer um desses quatro pontos.
+- `references/checklist-deploy.md` — checklist das 8 vulnerabilidades mais comuns (HTTPS, validação no servidor, secrets, rate limit, CSP, upload, SQL injection, backup), em formato de auditoria pré-deploy. Carregar antes de um deploy ou revisão de segurança formal.
 
 ## Checklist de revisão rápida
 - [ ] Todos os inputs do usuário são validados e sanitizados?

package/src/skills-lib/web-security/references/checklist-deploy.md

@@ -0,0 +1,52 @@
+# Checklist das 8 Vulnerabilidades Mais Comuns
+
+Carregue este arquivo para uma auditoria rápida antes de deploy ou revisão de segurança.
+
+## 1. HTTPS forçado
+- [ ] A plataforma força HTTPS? (Vercel: sim por padrão)
+- [ ] Header `Strict-Transport-Security` configurado explicitamente no código?
+- [ ] Nenhuma URL `http://` hardcoded em redirects ou fetch?
+
+## 2. Validação no servidor
+- [ ] Todo endpoint de API valida input com Zod (`.parse()` ou `.safeParse()`)?
+- [ ] `workspaceId`/`userId` validados como UUID antes de ir ao banco?
+- [ ] Regras de negócio re-validadas no backend (nunca confiar só no cliente)?
+- [ ] Supabase: RLS ativo nas tabelas? Queries sempre filtram por `workspace_id`/`user_id`?
+
+## 3. Senha do banco / secrets no código
+- [ ] Nenhum secret hardcoded em `.ts`/`.tsx`/`.js`?
+- [ ] `.env*` no `.gitignore`? (`git check-ignore -v .env.local`)
+- [ ] `.env.local` nunca aparece em `git log --all`?
+- [ ] Cripto usa chave de `process.env`, sem fallback de string?
+- [ ] Grep de segurança: `grep -r "sk_live\|sk_test\|service_role\|eyJ" src/` → vazio?
+
+## 4. Rate limiting na API
+- [ ] Endpoints de autenticação têm rate limit por IP?
+- [ ] Endpoints de cobrança (checkout, portal Stripe) têm rate limit?
+- [ ] Endpoints que disparam operações caras/externas têm rate limit?
+- [ ] Endpoints de admin têm rate limit + comparação timing-safe?
+- [ ] Rotas de escrita de estado falham fechado se o rate limiter cair? (ex: `failOpen: false` na lib)
+
+## 5. Content Security Policy
+- [ ] Header `Content-Security-Policy` configurado? (`next.config.ts` `headers()` ou middleware)
+- [ ] `X-Frame-Options: DENY` configurado?
+- [ ] `X-Content-Type-Options: nosniff` configurado?
+- [ ] CSP testada em dev sem erros no console?
+
+## 6. Upload sem verificação de tipo
+- [ ] Se há upload: verifica MIME type no servidor (não só no cliente)?
+- [ ] Limite de tamanho de arquivo imposto no servidor?
+- [ ] Extensões permitidas em allowlist (não blocklist)?
+- [ ] Se não há upload: confirmar que não há `<input type="file">` escondido?
+
+## 7. SQL injection na busca
+- [ ] Nenhuma query monta SQL com string interpolation/concatenação?
+- [ ] Supabase: todo acesso via query-builder (`.from().select().eq()`) ou RPC com params nomeados?
+- [ ] RPCs Postgres auditadas no dashboard: não usam `EXECUTE format(...)` com input do usuário?
+- [ ] Grep: `grep -r "\.sql\|raw(\|\.query(" src/` → revisar resultados?
+
+## 8. Backup automatizado
+- [ ] Plano Supabase tem PITR ou backup diário habilitado? (verificar no dashboard)
+- [ ] Retenção de backup documentada?
+- [ ] Existe runbook de restauração?
+- [ ] Credenciais de backup protegidas (não no repo)?

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

@@ -0,0 +1,78 @@
+# Headers de Segurança, Rate Limiting, CORS, e Vazamento de Dados
+
+Carregue este arquivo ao implementar/revisar headers de segurança, rate limiting, CORS, ou o formato de resposta de uma API (over-fetch/PII).
+
+## Headers de segurança obrigatórios
+
+`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.
+
+```
+Content-Security-Policy: default-src 'self'; frame-ancestors 'none'
+X-Frame-Options: DENY
+X-Content-Type-Options: nosniff
+Strict-Transport-Security: max-age=63072000; includeSubDomains; preload
+Referrer-Policy: strict-origin-when-cross-origin
+Permissions-Policy: camera=(), microphone=(), geolocation=()
+```
+
+Como adicionar em Next.js (`next.config.ts`):
+```ts
+async headers() {
+  return [
+    {
+      source: "/(.*)",
+      headers: [
+        { key: "X-Frame-Options", value: "DENY" },
+        { key: "X-Content-Type-Options", value: "nosniff" },
+        { key: "Referrer-Policy", value: "strict-origin-when-cross-origin" },
+        { key: "Strict-Transport-Security", value: "max-age=63072000; includeSubDomains; preload" },
+        { key: "Permissions-Policy", value: "camera=(), microphone=(), geolocation=()" },
+        {
+          key: "Content-Security-Policy",
+          value: [
+            "default-src 'self'",
+            "script-src 'self' 'unsafe-inline' https://js.clerk.dev https://js.stripe.com https://www.googletagmanager.com",
+            "connect-src 'self' https://*.supabase.co https://api.clerk.dev https://api.stripe.com",
+            "frame-src https://js.stripe.com https://hooks.stripe.com",
+            "img-src 'self' data: https:",
+            "style-src 'self' 'unsafe-inline'",
+          ].join("; "),
+        },
+      ],
+    },
+  ]
+},
+```
+
+> **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.
+
+## 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 auth-and-secrets)
+- Sem rate limit = brute force de graça. Somar lockout/CAPTCHA após N falhas no login
+
+## 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)
+```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("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

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

@@ -0,0 +1,51 @@
+# OWASP — Detalhe das 5 categorias mais comuns
+
+Carregue este arquivo ao aprofundar numa das falhas do triage rápido (seções 1-5 referenciadas na tabela do SKILL.md).
+
+## 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)
+
+Exemplo anti-IDOR (Next.js + Clerk + Supabase):
+```ts
+// app/api/projects/[id]/route.ts
+import { auth } from "@clerk/nextjs/server"
+
+export async function GET(req: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { userId } = await auth()
+  if (!userId) return new Response("Unauthorized", { status: 401 })
+  const { id } = await params
+  const { data } = await supabase
+    .from("projects")
+    .select("id, name")
+    .eq("id", id)
+    .eq("user_id", userId) // posse verificada na query, além do RLS
+    .single()
+  if (!data) return new Response("Not found", { status: 404 }) // 404, não 403 (não confirma que o recurso existe)
+  return Response.json(data)
+}
+```
+
+## 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)
+
+## 3. Injection
+- SQL: queries parametrizadas sempre
+- XSS: sanitize outputs, use Content-Security-Policy
+- Command injection: nunca execute input do usuário como comando shell
+
+## 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
+
+## 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