@luanpdd/kit-mcp 1.20.0 → 1.21.0

package/gates/dept-cycle-prevention.md

@@ -0,0 +1,179 @@
+---
+id: dept-cycle-prevention
+stage: pre-verify
+blocking: true
+description: Detecta tabela departments (ou similar) com parent_id FK self-referencial mas sem trigger anti-cycle. Loop circular em dept hierarchy esgota connection pool via WITH RECURSIVE infinito. Skip se projeto não tem supabase/migrations/.
+---
+
+# Department Cycle Prevention gate
+
+**When to run:** pre-verify (blocking — anti-pitfall P0 multi-tenant hierarchy).
+
+## Check
+
+```bash
+#!/usr/bin/env bash
+# PT-BR: detecta departments com parent_id self-referencial sem trigger anti-cycle.
+# Anti-pitfall #3 multi-tenant: dept hierarchy com loop circular (A.parent=B, B.parent=A) → WITH RECURSIVE infinito → connection pool exhaustion.
+# Bash 3.2-portable (macOS default).
+set -e
+
+MIGRATIONS_DIR="supabase/migrations"
+
+if [ ! -d "$MIGRATIONS_DIR" ]; then
+  echo "INFO: $MIGRATIONS_DIR não existe — projeto não usa Supabase migrations. Gate skipped."
+  exit 0
+fi
+
+# PT-BR: nomes comuns de tabelas hierárquicas (departments + variantes)
+HIERARCHY_TABLE_PATTERNS="departments|teams|groups|categories|nodes|tree"
+
+VIOLATIONS=0
+VIOLATIONS_DETAIL=""
+
+# PT-BR: iterar migrations em ordem cronológica
+MIGRATION_FILES=$(ls "$MIGRATIONS_DIR"/*.sql 2>/dev/null | sort)
+
+if [ -z "$MIGRATION_FILES" ]; then
+  echo "INFO: nenhum arquivo .sql em $MIGRATIONS_DIR — gate skipped."
+  exit 0
+fi
+
+# PT-BR: encontrar tabelas com parent_id auto-referencial (heurística: parent_id + REFERENCES <self>)
+SELF_REF_TABLES=""
+
+for f in $MIGRATION_FILES; do
+  # PT-BR: detecta padrão "parent_id ... references public.<table>(id)" onde <table> bate com nome da tabela sendo criada
+  # (case-insensitive, multi-line awk porque DDL pode ter quebras de linha)
+  TABLES_IN_FILE=$(awk '
+    BEGIN { in_create = 0; current_table = "" }
+    /create[ \t]+table[ \t]+(if[ \t]+not[ \t]+exists[ \t]+)?[a-z_]+\.[a-z_]+/ {
+      in_create = 1
+      match($0, /create[ \t]+table[ \t]+(if[ \t]+not[ \t]+exists[ \t]+)?([a-z_]+\.[a-z_]+)/)
+      if (RSTART > 0) {
+        # extrair só o último match group (table name)
+        s = substr($0, RSTART, RLENGTH)
+        n = split(s, parts, /[ \t]+/)
+        current_table = parts[n]
+      }
+      next
+    }
+    in_create && /parent_id[ \t]+uuid[ \t]+references[ \t]+([a-z_]+\.[a-z_]+)/ {
+      match($0, /references[ \t]+([a-z_]+\.[a-z_]+)/)
+      if (RSTART > 0) {
+        ref_table = substr($0, RSTART + 11, RLENGTH - 11)
+        gsub(/[ \t]/, "", ref_table)
+        if (ref_table == current_table) {
+          print current_table
+        }
+      }
+    }
+    /;[ \t]*$/ && in_create { in_create = 0; current_table = "" }
+  ' "$f" 2>/dev/null)
+
+  if [ -n "$TABLES_IN_FILE" ]; then
+    SELF_REF_TABLES="$SELF_REF_TABLES
+$TABLES_IN_FILE"
+  fi
+done
+
+# PT-BR: filtrar entries vazias
+SELF_REF_TABLES=$(echo "$SELF_REF_TABLES" | grep -v "^$" | sort -u)
+
+if [ -z "$SELF_REF_TABLES" ]; then
+  echo "INFO: nenhuma tabela com parent_id self-referencial detectada — gate skipped."
+  exit 0
+fi
+
+# PT-BR: para cada tabela self-ref, verificar se há trigger ou function anti-cycle
+for table in $SELF_REF_TABLES; do
+  # PT-BR: extrair só nome da tabela (sem schema)
+  table_name=$(echo "$table" | awk -F. '{print $2}')
+
+  # PT-BR: heurística: procurar trigger com nome contendo cycle/loop/recursion + tabela
+  CYCLE_GUARD_FOUND=0
+  for f in $MIGRATION_FILES; do
+    if grep -iE "(create[ \t]+(or[ \t]+replace[ \t]+)?(function|trigger))[ \t]+[a-z_]*(cycle|loop|recurs|hierarchy_check|anti_cycle)" "$f" 2>/dev/null \
+       | grep -iqE "$table_name|$(echo "$table" | tr '.' '_')"; then
+      CYCLE_GUARD_FOUND=1
+      break
+    fi
+
+    # PT-BR: pattern alternativo: trigger genérico que menciona a tabela e WITH RECURSIVE em corpo
+    if grep -iqE "create[ \t]+trigger.*on[ \t]+$table" "$f" 2>/dev/null \
+       && grep -iqE "with[ \t]+recursive.*parent_id" "$f" 2>/dev/null; then
+      CYCLE_GUARD_FOUND=1
+      break
+    fi
+  done
+
+  if [ "$CYCLE_GUARD_FOUND" -eq 0 ]; then
+    VIOLATIONS=$((VIOLATIONS + 1))
+    VIOLATIONS_DETAIL="${VIOLATIONS_DETAIL}
+  Tabela '$table' tem parent_id self-referencial mas sem trigger anti-cycle detectado"
+  fi
+done
+
+if [ "$VIOLATIONS" -eq 0 ]; then
+  echo "PASS: todas as tabelas hierárquicas têm proteção anti-cycle."
+  exit 0
+else
+  echo "FAIL: $VIOLATIONS tabela(s) hierárquica(s) sem trigger anti-cycle:$VIOLATIONS_DETAIL"
+  echo ""
+  echo "Fix: adicionar trigger BEFORE INSERT/UPDATE que detecta cycle via WITH RECURSIVE:"
+  cat << 'EOF'
+
+  create or replace function private.check_no_dept_cycle()
+  returns trigger
+  language plpgsql
+  security invoker
+  set search_path = ''
+  as $$
+  declare
+    cycle_detected boolean;
+  begin
+    if new.parent_id is null then return new; end if;
+
+    with recursive ancestors as (
+      select id, parent_id, 1 as depth from public.departments where id = new.parent_id
+      union all
+      select d.id, d.parent_id, a.depth + 1
+      from public.departments d
+      join ancestors a on d.id = a.parent_id
+      where a.depth < 10  -- max 10 níveis
+    )
+    select exists (select 1 from ancestors where id = new.id) into cycle_detected;
+
+    if cycle_detected then
+      raise exception 'department hierarchy cycle detected: % cannot be parent of %',
+        new.parent_id, new.id;
+    end if;
+
+    return new;
+  end;
+  $$;
+
+  create trigger check_no_dept_cycle_trigger
+    before insert or update of parent_id on public.departments
+    for each row execute function private.check_no_dept_cycle();
+
+EOF
+  echo "Ref: kit/skills/_shared-multi-tenant/glossary.md (Department Hierarchy)"
+  exit 1
+fi
+```
+
+## Verdict
+
+- **passed** — todas tabelas hierárquicas têm proteção anti-cycle → continuar
+- **block** — apresentar tabelas violadoras + DDL pronto do trigger anti-cycle
+
+## Notes
+
+Detecção é heurística baseada em naming (`parent_id` + `references <self_table>`). Pode produzir:
+- **Falso-negativo** se a coluna se chamar `parent` em vez de `parent_id`, ou referenciar tabela diferente (não self-ref)
+- **Falso-positivo** se o nome do trigger não contém palavras-chave (`cycle`, `loop`, `recurs`, `anti_cycle`) — neste caso, renomear o trigger ou estender a allowlist do gate
+
+Tabelas hierárquicas tipicamente afetadas: `departments`, `teams`, `groups`, `categories`, `nodes`, `tree`.
+
+Limit recursivo padrão sugerido: 10 níveis. Hierarquia mais profunda que isso indica modelagem questionável (Linear/Notion suportam até 5 níveis).

package/gates/multi-tenant-rls-coverage.md

@@ -0,0 +1,102 @@
+---
+id: multi-tenant-rls-coverage
+stage: pre-verify
+blocking: true
+description: Detecta CREATE TABLE em supabase/migrations/ sem ENABLE ROW LEVEL SECURITY no mesmo arquivo. Cross-tenant data leak silencioso é a falha #1 de apps multi-tenant Supabase. Skip se projeto não tem supabase/migrations/.
+---
+
+# Multi-Tenant RLS Coverage gate
+
+**When to run:** pre-verify (blocking — multi-tenant phase não verifica até cobertura completa).
+
+## Check
+
+```bash
+#!/usr/bin/env bash
+# PT-BR: detecta CREATE TABLE em supabase/migrations/ sem ENABLE ROW LEVEL SECURITY no mesmo arquivo.
+# Anti-pitfall #1 multi-tenant: tabela nova sem RLS = cross-tenant leak silencioso (Postgres não aplica policies automaticamente).
+# Bash 3.2-portable (macOS default).
+set -e
+
+MIGRATIONS_DIR="supabase/migrations"
+
+# PT-BR: skip gracioso se projeto não tem migrations Supabase
+if [ ! -d "$MIGRATIONS_DIR" ]; then
+  echo "INFO: $MIGRATIONS_DIR não existe — projeto não usa Supabase migrations. Gate skipped."
+  exit 0
+fi
+
+# PT-BR: tabelas em schemas system não exigem RLS (auth, storage, realtime, vault, supabase_*)
+SYSTEM_SCHEMA_PREFIXES="auth\\.|storage\\.|realtime\\.|vault\\.|supabase_|extensions\\."
+
+# PT-BR: allowlist de tabelas que conscientemente não têm RLS (ex: lookup tables públicas)
+ALLOWLIST_TABLES=(
+  "public.permissions"  # catálogo global de permissions, leitura pública por design
+)
+
+is_allowlisted() {
+  local table="$1"
+  for at in "${ALLOWLIST_TABLES[@]}"; do
+    [ "$table" = "$at" ] && return 0
+  done
+  return 1
+}
+
+VIOLATIONS=0
+VIOLATIONS_DETAIL=""
+
+# PT-BR: iterar migrations em ordem cronológica
+MIGRATION_FILES=$(ls "$MIGRATIONS_DIR"/*.sql 2>/dev/null | sort)
+
+if [ -z "$MIGRATION_FILES" ]; then
+  echo "INFO: nenhum arquivo .sql em $MIGRATIONS_DIR — gate skipped."
+  exit 0
+fi
+
+for f in $MIGRATION_FILES; do
+  # PT-BR: extrair tabelas criadas via CREATE TABLE (case-insensitive, ignora IF NOT EXISTS)
+  CREATED_TABLES=$(grep -iE "^create\s+table\s+(if\s+not\s+exists\s+)?[a-z_]+\." "$f" 2>/dev/null \
+    | sed -E 's/.*create\s+table\s+(if\s+not\s+exists\s+)?([a-z_]+\.[a-z_]+).*/\2/i' \
+    | grep -viE "$SYSTEM_SCHEMA_PREFIXES" || true)
+
+  # PT-BR: extrair tabelas com RLS habilitada no MESMO arquivo
+  RLS_TABLES=$(grep -iE "alter\s+table\s+[a-z_]+\.[a-z_]+\s+enable\s+row\s+level\s+security" "$f" 2>/dev/null \
+    | sed -E 's/.*alter\s+table\s+([a-z_]+\.[a-z_]+)\s+enable.*/\1/i' || true)
+
+  # PT-BR: para cada tabela criada, checar se RLS foi habilitada
+  for table in $CREATED_TABLES; do
+    [ -z "$table" ] && continue
+    is_allowlisted "$table" && continue
+
+    if ! echo "$RLS_TABLES" | grep -qFx "$table"; then
+      VIOLATIONS=$((VIOLATIONS + 1))
+      VIOLATIONS_DETAIL="${VIOLATIONS_DETAIL}
+  $(basename "$f"): tabela '$table' criada sem ENABLE ROW LEVEL SECURITY"
+    fi
+  done
+done
+
+if [ "$VIOLATIONS" -eq 0 ]; then
+  echo "PASS: todas as tabelas em supabase/migrations/ têm RLS habilitada no mesmo arquivo de criação."
+  exit 0
+else
+  echo "FAIL: $VIOLATIONS tabela(s) criada(s) sem ENABLE ROW LEVEL SECURITY:$VIOLATIONS_DETAIL"
+  echo ""
+  echo "Fix: adicione 'alter table <schema>.<table> enable row level security;' no MESMO arquivo de migration que criou a tabela."
+  echo "Ref: kit/skills/multi-tenant-rls-hierarchy/SKILL.md (REGRA #1)"
+  exit 1
+fi
+```
+
+## Verdict
+
+- **passed** — todas tabelas multi-tenant têm RLS habilitada → continuar
+- **block** — apresentar tabela de violations + sugestão de fix; sem opção de skip (anti-pitfall P0 — cross-tenant leak)
+
+## Notes
+
+Este gate só checa **habilitação** de RLS — não checa se as policies cobrem todos os casos. Ver `multi-tenant-isolation-auditor` agent para análise completa de policies (requer MCP Supabase ativo para query a `pg_policies`).
+
+Tabelas em schemas system (`auth.*`, `storage.*`, `realtime.*`, `vault.*`, `supabase_*`, `extensions.*`) são automaticamente skipped — Supabase já aplica RLS interno nelas.
+
+Allowlist mínima: `public.permissions` (catálogo global de permissions, leitura pública por design — tem `to authenticated` em SELECT mas sem isolamento por tenant).

package/gates/service-role-not-in-user-facing.md

@@ -0,0 +1,113 @@
+---
+id: service-role-not-in-user-facing
+stage: pre-verify
+blocking: true
+description: Detecta uso de SUPABASE_SERVICE_ROLE_KEY em Edge Functions com verify_jwt:true (user-facing). Service role bypassa RLS — uso em rota acessível a usuário desliga toda autorização. Skip se projeto não tem supabase/functions/.
+---
+
+# Service Role Not In User-Facing gate
+
+**When to run:** pre-verify (blocking — anti-pitfall P0 multi-tenant).
+
+## Check
+
+```bash
+#!/usr/bin/env bash
+# PT-BR: detecta uso de SUPABASE_SERVICE_ROLE_KEY em Edge Functions com verify_jwt:true.
+# Anti-pitfall #2 multi-tenant: service role em rota user-facing = bypass total de RLS.
+# Bash 3.2-portable (macOS default).
+set -e
+
+FUNCTIONS_DIR="supabase/functions"
+CONFIG_FILE="supabase/config.toml"
+
+if [ ! -d "$FUNCTIONS_DIR" ]; then
+  echo "INFO: $FUNCTIONS_DIR não existe — projeto não usa Supabase Edge Functions. Gate skipped."
+  exit 0
+fi
+
+# PT-BR: env vars que indicam uso de service role
+SERVICE_ROLE_PATTERNS="SUPABASE_SERVICE_ROLE_KEY|SERVICE_ROLE_KEY|service_role_key|serviceRoleKey"
+
+VIOLATIONS=0
+VIOLATIONS_DETAIL=""
+
+# PT-BR: iterar cada Edge Function (cada subdir em functions/)
+FUNCTION_DIRS=$(find "$FUNCTIONS_DIR" -mindepth 1 -maxdepth 1 -type d 2>/dev/null)
+
+if [ -z "$FUNCTION_DIRS" ]; then
+  echo "INFO: nenhuma Edge Function em $FUNCTIONS_DIR — gate skipped."
+  exit 0
+fi
+
+for fn_dir in $FUNCTION_DIRS; do
+  fn_name=$(basename "$fn_dir")
+
+  # PT-BR: skip _shared (não é Edge Function deployable)
+  [ "$fn_name" = "_shared" ] && continue
+
+  # PT-BR: descobrir verify_jwt setting da função (default: true se ausente)
+  VERIFY_JWT="true"  # default Supabase
+  if [ -f "$CONFIG_FILE" ]; then
+    # PT-BR: parsing leve — procurar [functions.<name>] block + verify_jwt
+    SECTION_VERIFY=$(awk -v fn="$fn_name" '
+      $0 ~ "^\\[functions\\." fn "\\]" { in_section = 1; next }
+      in_section && /^\[/ { in_section = 0 }
+      in_section && /verify_jwt/ {
+        gsub(/[ \t]/, "")
+        split($0, a, "=")
+        print a[2]
+        exit
+      }
+    ' "$CONFIG_FILE" 2>/dev/null)
+
+    if [ -n "$SECTION_VERIFY" ]; then
+      VERIFY_JWT="$SECTION_VERIFY"
+    fi
+  fi
+
+  # PT-BR: se verify_jwt=false (webhook/internal), skip — service role é OK aqui
+  if [ "$VERIFY_JWT" = "false" ]; then
+    continue
+  fi
+
+  # PT-BR: buscar uso de service role em arquivos .ts/.js da function
+  SERVICE_ROLE_FILES=$(grep -rlE "$SERVICE_ROLE_PATTERNS" "$fn_dir" --include="*.ts" --include="*.js" --include="*.mjs" 2>/dev/null || true)
+
+  if [ -n "$SERVICE_ROLE_FILES" ]; then
+    VIOLATIONS=$((VIOLATIONS + 1))
+    VIOLATIONS_DETAIL="${VIOLATIONS_DETAIL}
+  Edge Function '$fn_name' (verify_jwt=$VERIFY_JWT) usa service role:
+$(echo "$SERVICE_ROLE_FILES" | sed 's/^/    /')"
+  fi
+done
+
+if [ "$VIOLATIONS" -eq 0 ]; then
+  echo "PASS: nenhuma Edge Function user-facing (verify_jwt=true) usa SERVICE_ROLE_KEY."
+  exit 0
+else
+  echo "FAIL: $VIOLATIONS Edge Function(s) user-facing usam SERVICE_ROLE_KEY:$VIOLATIONS_DETAIL"
+  echo ""
+  echo "Fix: use ANON_KEY com JWT do user para preservar RLS. Se realmente precisa de service role:"
+  echo "  - Mover lógica privilegiada para Edge Function separada com verify_jwt=false (webhook ou cron-only)"
+  echo "  - OU validar manualmente quem está chamando antes de usar service role (anti-pattern, mas explícito)"
+  echo "Ref: kit/skills/_shared-multi-tenant/glossary.md (sub-seção super_admin) + kit/skills/supabase-rls-policies/SKILL.md"
+  exit 1
+fi
+```
+
+## Verdict
+
+- **passed** — nenhum service role em Edge Function user-facing → continuar
+- **block** — apresentar lista de Edge Functions violadoras + fix recomendado
+
+## Notes
+
+Edge Functions com `verify_jwt = false` (webhooks Evolution Go, Stripe, schedulers internos via pg_cron) podem usar service role legitimamente — gate skippa essas.
+
+Detecção pode produzir falso-positivo se code referencia o nome da var em comentário ou string literal (ex: documentação dentro do code). Para suprimir, mover documentação para arquivo externo ou usar comentário JSDoc fora do regex match.
+
+Para super-admin operations user-facing (impersonation, cross-tenant queries), pattern correto é:
+1. Endpoint user-facing valida `super_admin: true` em JWT app_metadata
+2. Endpoint chama segunda Edge Function interna (verify_jwt=false) que usa service role
+3. Audit log obrigatório no caminho