@luanpdd/kit-mcp 1.30.2 → 1.32.0

package/kit/skills/supabase-edge-functions/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: supabase-edge-functions
-description: Use ao escrever Edge Functions Supabase — Deno + imports versionados npm:/jsr:/node:, env vars 2026 (JSON dict SUPABASE_PUBLISHABLE_KEYS/SUPABASE_SECRET_KEYS), per-function deno.json, config.toml por função (verify_jwt, entrypoint, static_files), file writes APENAS em /tmp ou /s3/<bucket>, EdgeRuntime.waitUntil, CORS via @supabase/supabase-js/cors v2.95+.
+description: Use ao escrever Edge Functions Supabase — Deno, imports versionados npm:/jsr:/node:, env vars JSON dict 2026, per-function deno.json + config.toml, file writes /tmp ou /s3, EdgeRuntime.waitUntil.
 ---
 
 # Supabase — Edge Functions (Deno) · 2026

package/kit/skills/supabase-edge-functions-auth/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: supabase-edge-functions-auth
-description: Use ao autenticar Edge Functions Supabase em 2026 — `@supabase/server` package, `withSupabase({auth: 'user'|'secret:name'|'publishable:name'|'none'})`, `createSupabaseContext` para erros customizados, distinção Authorization (JWT) vs apikey (API key), toggle `verify_jwt` por função em config.toml, padrões canônicos para webhooks/service-to-service/user-facing/public.
+description: Use ao autenticar Edge Functions Supabase 2026 — package @supabase/server, withSupabase({auth}), createSupabaseContext, Authorization JWT vs apikey, toggle verify_jwt por função no config.toml.
 ---
 
 # Supabase — Edge Functions Auth (`@supabase/server`) · 2026

package/kit/skills/supabase-edge-functions-limits/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: supabase-edge-functions-limits
-description: Use ao planejar limites, falhas e retries em Edge Functions Supabase — runtime caps (256MB / 2s CPU / 150-400s wall clock), platform caps (20MB bundle, 100/500/1000 funcs por plano), status codes canônicos (401/404/405/500/503/504/546 WORKER_LIMIT), recursive call budget ~5k req/min com `RateLimitError` + `retryAfterMs`, client-side error classes `FunctionsHttpError`/`FunctionsRelayError`/`FunctionsFetchError`, idempotency e backoff.
+description: Use ao planejar limites e retries em Edge Functions Supabase — runtime caps 256MB/2s CPU/wall clock, status codes canônicos, RateLimitError + retryAfterMs, error classes client-side, idempotency.
 ---
 
 # Supabase — Edge Functions Limits, Status Codes & Rate Limits · 2026

package/kit/skills/supabase-edge-functions-mcp-server/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: supabase-edge-functions-mcp-server
-description: Use ao construir MCP server (Model Context Protocol) em Supabase Edge Functions com `mcp-lite` — scaffolding via `npm create mcp-lite@latest` template "Supabase Edge Functions (MCP server)", pattern dois apps Hono (root mounta em /<function-name>, inner handle /mcp), deno.json com imports `mcp-lite`/`hono`/`zod`, `verify_jwt=false` no template + auth no nível MCP, deploy a `https://<ref>.supabase.co/functions/v1/mcp-server/mcp` exposed para Claude/Cursor.
+description: Use ao construir MCP server em Supabase Edge Functions com mcp-lite — scaffold npm create mcp-lite, dois apps Hono, deno.json, verify_jwt=false + auth no nível MCP, deploy para Claude/Cursor.
 ---
 
 # Supabase — Edge Functions como MCP Server (`mcp-lite`) · 2026

package/kit/skills/supabase-edge-functions-testing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: supabase-edge-functions-testing
-description: Use ao testar/debugar Edge Functions Supabase localmente — `deno test --allow-all` com `Deno.test`, folder structure `supabase/functions/tests/<fn>-test.ts`, `supabase start` + `supabase functions serve --env-file`, Chrome DevTools via `--inspect-mode brk` na porta 8083, `per_worker` policy para WebSocket/background, charset .env local, characterization tests para Edge Functions legadas.
+description: Use ao testar/debugar Edge Functions Supabase localmente — deno test --allow-all, folder tests/<fn>-test.ts, supabase functions serve, Chrome DevTools --inspect-mode, characterization para legadas.
 ---
 
 # Supabase — Edge Functions Testing & Local Debug · 2026

package/kit/skills/supabase-edge-runtime-builtins/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: supabase-edge-runtime-builtins
-description: Use ao usar built-ins do Edge Runtime Supabase — `Supabase.ai.Session` para embeddings/LLM (gte-small + Ollama/Llamafile), file system persistente via S3FS (`/s3/<bucket>`) + ephemeral (`/tmp`), regional invocation via `x-region` header e `FunctionRegion` enum, WebSockets com `Deno.upgradeWebSocket` + `per_worker` policy, Wasm modules com `static_files` em config.toml, env vars runtime (SB_REGION, SB_EXECUTION_ID, DENO_DEPLOYMENT_ID).
+description: Use ao usar built-ins do Edge Runtime Supabase — Supabase.ai.Session (embeddings/LLM), file system S3FS /s3 + /tmp, regional via x-region, WebSockets Deno.upgradeWebSocket, Wasm via static_files.
 ---
 
 # Supabase — Edge Runtime Built-ins · 2026

package/kit/skills/supabase-enterprise-sso-saml/SKILL.md

@@ -0,0 +1,545 @@
+---
+name: supabase-enterprise-sso-saml
+description: Use ao configurar Enterprise SSO via SAML 2.0 no Supabase — Okta, Azure AD, Google Workspace, signInWithSSO, attribute mapping e RLS multi-tenant.
+---
+
+# Supabase — Enterprise SSO (SAML 2.0)
+
+## Quando usar
+
+LLM carrega esta skill quando configurar **Single Sign-On empresarial via SAML 2.0** no Supabase, integrando com provedores de identidade (IdP) como Okta, Azure AD/Entra ID, Google Workspace ou PingIdentity.
+
+Trigger phrases:
+
+- "SAML SSO Supabase", "signInWithSSO"
+- "enterprise single sign-on", "Okta Supabase"
+- "Azure AD SAML", "Entra ID Supabase"
+- "attribute mapping SAML", "multi-tenant SSO"
+- "identity provider Supabase", "SP-initiated flow"
+- "supabase sso add", "sso_provider_id RLS"
+
+## Princípio canônico
+
+SSO via SAML 2.0 permite que empresas clientes (tenants) façam login com suas credenciais corporativas existentes, sem criar senhas no Supabase. O Supabase atua como **Service Provider (SP)** e o sistema da empresa (Okta, Azure AD, etc.) é o **Identity Provider (IdP)**.
+
+**Disponibilidade:** SAML SSO exige plano **Pro ou superior** do Supabase.
+
+**Providers SAML suportados (testados):**
+
+| Provider | Observação |
+|----------|------------|
+| Okta | Provider mais comum em B2B enterprise |
+| Azure AD / Entra ID | Microsoft identity — integração via app enterprise |
+| Google Workspace | Apenas org-level SSO (não contas pessoais Google) |
+| PingIdentity | Usado em grandes enterprises financeiras |
+| OneLogin | Alternativa frequente em médias empresas |
+| Auth0 (como IdP) | Quando o tenant usa Auth0 para SSO interno |
+
+**Quando usar SSO SAML:**
+
+- ✅ B2B SaaS com clientes enterprise que exigem login corporativo
+- ✅ Compliance que exige autenticação via IdP central da empresa
+- ✅ Migração de usuários — empresa já tem Okta/Azure com todos os colaboradores
+- ✅ Multi-tenant onde cada tenant tem seu próprio IdP
+
+**Quando NÃO usar SSO SAML:**
+
+- ❌ Aplicação B2C (usuários comuns) — use OAuth social ou magic link
+- ❌ Plano Free do Supabase — SAML exige Pro+
+- ❌ Poucos usuários que podem usar email/senha — overhead de configuração não compensa
+
+## Terminologia SAML
+
+| Termo | Significado |
+|-------|-------------|
+| **Identity Provider (IdP)** | Sistema que autentica o usuário (Okta, Azure AD) |
+| **Service Provider (SP)** | Seu aplicativo (Supabase) — confia no IdP |
+| **EntityID** | Identificador único do SP/IdP (geralmente uma URL) |
+| **NameID** | Identificador do usuário no SAML assertion (email ou UUID) |
+| **Assertion** | Documento XML assinado que o IdP envia ao SP após autenticação |
+| **Metadata** | XML descrevendo endpoints, certificados e configurações do SP/IdP |
+| **Certificate** | Certificado X.509 para assinar/verificar assertions |
+| **ACS URL** | Assertion Consumer Service — endpoint do SP que recebe o assertion |
+| **Binding** | Método de transporte (HTTP-POST ou HTTP-Redirect) |
+| **RelayState** | Parâmetro opaco passado pelo SP ao IdP para manter estado (ex: URL de destino) |
+
+## URLs SAML do Projeto Supabase
+
+O Supabase expõe endpoints SAML padrão para cada projeto:
+
+| Endpoint | URL |
+|----------|-----|
+| **Metadata (EntityID)** | `https://<project-ref>.supabase.co/auth/v1/sso/saml/metadata` |
+| **ACS URL** | `https://<project-ref>.supabase.co/auth/v1/sso/saml/acs` |
+
+**NameID:** configurar no IdP para enviar `emailAddress` (formato `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`) ou `persistent` (UUID opaco). Prefira `persistent` em ambientes onde o email pode mudar.
+
+**Configurar no IdP (exemplo Okta):**
+
+1. No Okta Admin Console → Applications → Create App Integration → SAML 2.0
+2. **Single Sign-On URL:** `https://<project-ref>.supabase.co/auth/v1/sso/saml/acs`
+3. **Audience URI (SP Entity ID):** `https://<project-ref>.supabase.co/auth/v1/sso/saml/metadata`
+4. **Name ID format:** `EmailAddress`
+5. Adicionar attribute mappings (ver seção abaixo)
+6. Baixar metadata XML do Okta para usar no `supabase sso add`
+
+## Gerenciar Conexões SSO via Supabase CLI
+
+**Requisito:** Supabase CLI v1.46.4 ou superior.
+
+```bash
+# verificar versão
+supabase --version  # deve ser >= 1.46.4
+
+# adicionar conexão SSO via metadata URL (Okta/Azure expõem URL de metadata)
+supabase sso add \
+  --project-ref <project-ref> \
+  --type saml \
+  --metadata-url https://okta.example.com/app/xxx/sso/saml/metadata \
+  --domains empresa.com,empresa.com.br
+
+# adicionar via arquivo XML (quando o IdP não expõe URL pública de metadata)
+supabase sso add \
+  --project-ref <project-ref> \
+  --type saml \
+  --metadata-file ./idp-metadata.xml \
+  --domains empresa.com
+
+# adicionar com attribute mapping customizado
+supabase sso add \
+  --project-ref <project-ref> \
+  --type saml \
+  --metadata-url https://okta.example.com/.../metadata \
+  --domains empresa.com \
+  --attribute-mapping-file ./attribute-mapping.json
+
+# listar todas as conexões SSO do projeto
+supabase sso list --project-ref <project-ref>
+
+# ver detalhes de uma conexão (inclui provider_id)
+supabase sso show --project-ref <project-ref> --sso-provider-id <uuid>
+
+# atualizar domains ou metadata de uma conexão
+supabase sso update \
+  --project-ref <project-ref> \
+  --sso-provider-id <uuid> \
+  --domains empresa.com,novodominio.com
+
+# remover conexão SSO
+supabase sso remove \
+  --project-ref <project-ref> \
+  --sso-provider-id <uuid>
+```
+
+## Fluxo SP-Initiated (padrão)
+
+O fluxo padrão é iniciado pelo SP (seu app) quando o usuário tenta acessar:
+
+```ts
+import { createClient } from '@supabase/supabase-js'
+
+const supabase = createClient(
+  process.env.NEXT_PUBLIC_SUPABASE_URL!,
+  process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!
+)
+
+// SP-initiated: identificar pelo domínio do email do usuário
+const iniciarSSO = async (email: string) => {
+  const dominio = email.split('@')[1]
+
+  const { data, error } = await supabase.auth.signInWithSSO({
+    domain: dominio,
+    options: {
+      redirectTo: `${window.location.origin}/auth/callback`,
+    },
+  })
+
+  if (error) {
+    console.error('Erro ao iniciar SSO:', error.message)
+    return
+  }
+
+  if (data?.url) {
+    // redirecionar para o IdP
+    window.location.href = data.url
+  }
+}
+
+// Alternativa: identificar pelo sso_provider_id (para multi-tenant com seleção explícita)
+const iniciarSSOPorProvider = async (ssoProviderId: string) => {
+  const { data, error } = await supabase.auth.signInWithSSO({
+    providerId: ssoProviderId,
+    options: {
+      redirectTo: `${window.location.origin}/auth/callback`,
+    },
+  })
+
+  if (data?.url) window.location.href = data.url
+}
+```
+
+**Callback — trocar code por sessão:**
+
+```ts
+// app/auth/callback/route.ts (Next.js Route Handler)
+import { createServerClient } from '@supabase/ssr'
+import { cookies } from 'next/headers'
+import { NextRequest, NextResponse } from 'next/server'
+
+export async function GET(request: NextRequest) {
+  const { searchParams } = new URL(request.url)
+  const code = searchParams.get('code')
+
+  if (code) {
+    const cookieStore = await cookies()
+    const supabase = createServerClient(
+      process.env.NEXT_PUBLIC_SUPABASE_URL!,
+      process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!,
+      {
+        cookies: {
+          getAll: () => cookieStore.getAll(),
+          setAll: (cookiesToSet) => {
+            cookiesToSet.forEach(({ name, value, options }) =>
+              cookieStore.set(name, value, options)
+            )
+          },
+        },
+      }
+    )
+
+    const { error } = await supabase.auth.exchangeCodeForSession(code)
+    if (!error) {
+      return NextResponse.redirect(new URL('/dashboard', request.url))
+    }
+  }
+
+  return NextResponse.redirect(new URL('/auth/error', request.url))
+}
+```
+
+## Attribute Mappings
+
+Attribute mappings definem como atributos SAML do IdP são mapeados para campos do usuário Supabase. Os dados mapeados ficam em `auth.identities.identity_data` e `auth.users.raw_user_meta_data`.
+
+**Formato do arquivo JSON de mapping:**
+
+```json
+{
+  "keys": {
+    "email": {
+      "name": "mail",
+      "names": ["email", "mail", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"]
+    },
+    "email_verified": {
+      "default": true
+    },
+    "first_name": {
+      "name": "givenName",
+      "names": ["firstName", "givenName", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"]
+    },
+    "last_name": {
+      "name": "sn",
+      "names": ["lastName", "sn", "surname", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"]
+    },
+    "department": {
+      "name": "department",
+      "array": false
+    },
+    "groups": {
+      "name": "groups",
+      "array": true
+    }
+  }
+}
+```
+
+**Campos do mapping:**
+
+| Campo | Tipo | Descrição |
+|-------|------|-----------|
+| `name` | string | Nome principal do atributo SAML |
+| `names` | string[] | Aliases (Supabase tenta cada um até encontrar) |
+| `array` | boolean | Se o atributo é multi-valor (ex: grupos) |
+| `default` | any | Valor padrão se o atributo não vier no assertion |
+
+**Acessar dados mapeados:**
+
+```sql
+-- em RLS policy ou função
+select raw_user_meta_data->>'department' from auth.users where id = auth.uid();
+select raw_user_meta_data->'groups' from auth.users where id = auth.uid();
+```
+
+```ts
+// no cliente
+const { data: { user } } = await supabase.auth.getUser()
+const department = user?.user_metadata?.department
+const groups = user?.user_metadata?.groups  // array se configurado como array: true
+```
+
+## Contas SSO — Diferenças Importantes
+
+Contas criadas via SSO têm comportamento diferente de contas email/senha:
+
+| Aspecto | Conta Email/Senha | Conta SSO |
+|---------|-------------------|-----------|
+| Auto-linking | Supabase pode vincular por email | **Sem auto-linking** — sempre cria nova identidade |
+| Unicidade de email | Emails são únicos por padrão | **Emails NÃO são únicos** — dois IdPs podem ter mesmo email |
+| Identificador seguro | Email | **UUID (`auth.uid()`)** |
+| Sessão máxima | Configurável via JWT TTL | Pode ter duração máxima definida pelo IdP |
+| Senha | Usuário tem senha | **Sem senha** — autenticação apenas via IdP |
+
+**Crítico:** nunca usar email como identificador primário em sistemas com SSO. Dois tenants (empresas) diferentes podem ter colaboradores com mesmo email se houver overlap de domínio — situação rara mas válida (ex: empresa A e empresa B ambas têm `joao@empresa.com` em seus diretórios).
+
+## RLS para Multi-tenant SSO
+
+O `sso_provider_id` no JWT identifica de qual conexão SSO o usuário veio — use como chave de isolamento de tenant:
+
+```sql
+-- extrair sso_provider_id do JWT
+-- retorna o UUID do IdP (conexão SSO configurada) ou null se não for SSO
+select auth.jwt()#>>'{amr,0,provider}' as sso_provider_id;
+
+-- tabela de configurações por tenant SSO
+create table public.organization_settings (
+  id                uuid default gen_random_uuid() primary key,
+  sso_provider_id   uuid not null unique,   -- UUID do provider SSO
+  organization_name text not null,
+  plan              text not null default 'pro',
+  max_users         int  not null default 100,
+  created_at        timestamptz default now()
+);
+comment on table public.organization_settings
+  is 'Configurações por tenant SSO — isolamento via sso_provider_id.';
+
+-- habilitar RLS
+alter table public.organization_settings enable row level security;
+
+-- política RESTRICTIVE — escopo de tenant SSO
+create policy "Tenant SSO só vê sua própria organização" on public.organization_settings
+  as restrictive
+  for select
+  to authenticated
+  using (
+    sso_provider_id = (auth.jwt()#>>'{amr,0,provider}')::uuid
+  );
+
+-- política permissiva para leitura
+create policy "Usuários autenticados podem ler config da org" on public.organization_settings
+  as permissive
+  for select
+  to authenticated
+  using (true);
+```
+
+**Tabela de recursos com escopo de tenant:**
+
+```sql
+create table public.projetos (
+  id              uuid default gen_random_uuid() primary key,
+  sso_provider_id uuid not null,   -- tenant owner
+  nome            text not null,
+  dados           jsonb,
+  criado_em       timestamptz default now()
+);
+
+alter table public.projetos enable row level security;
+
+-- escopo rígido por tenant SSO
+create policy "Usuário vê apenas projetos do seu tenant" on public.projetos
+  as restrictive
+  for all
+  to authenticated
+  using (
+    sso_provider_id = (auth.jwt()#>>'{amr,0,provider}')::uuid
+  );
+```
+
+**Helper function para uso em múltiplas policies:**
+
+```sql
+create or replace function public.sso_provider_id() returns uuid
+language sql stable security definer set search_path = ''
+as $$
+  select (auth.jwt()#>>'{amr,0,provider}')::uuid
+$$;
+
+-- uso simplificado em policies
+create policy "Tenant isolado" on public.projetos
+  as restrictive for all to authenticated
+  using ((select public.sso_provider_id()) = sso_provider_id);
+```
+
+## IdP-Initiated Flow — Caveat PKCE
+
+**IdP-initiated flow** é quando o usuário clica em um ícone no portal do IdP (ex: Okta App Dashboard) para acessar o app — sem que o SP inicie o fluxo.
+
+**Problema:** IdP-initiated é **incompatível com PKCE** porque não há `state` do SP para validar o `code_verifier`.
+
+**Solução — Padrão "Bookmark App":**
+
+```ts
+// 1. Criar um endpoint que inicia o SP-initiated flow
+// app/auth/sso-bookmark/route.ts
+import { NextRequest, NextResponse } from 'next/server'
+import { createServerClient } from '@supabase/ssr'
+import { cookies } from 'next/headers'
+
+export async function GET(request: NextRequest) {
+  const { searchParams } = new URL(request.url)
+  const providerId = searchParams.get('provider_id')
+  const tenant = searchParams.get('tenant')  // para multi-tenant
+
+  if (!providerId && !tenant) {
+    return NextResponse.redirect(new URL('/auth/error', request.url))
+  }
+
+  const cookieStore = await cookies()
+  const supabase = createServerClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!,
+    { cookies: { getAll: () => cookieStore.getAll(), setAll: () => {} } }
+  )
+
+  // iniciar SP-initiated (não IdP-initiated)
+  const { data, error } = await supabase.auth.signInWithSSO({
+    ...(providerId ? { providerId } : { domain: `${tenant}.empresa.com` }),
+    options: {
+      redirectTo: `${process.env.NEXT_PUBLIC_SITE_URL}/auth/callback`,
+    },
+  })
+
+  if (data?.url) return NextResponse.redirect(data.url)
+  return NextResponse.redirect(new URL('/auth/error', request.url))
+}
+
+// 2. No Okta/Azure: configurar o ícone do app para apontar para:
+//    https://seu-app.com/auth/sso-bookmark?provider_id=<uuid-do-provider>
+//    (não para o ACS URL diretamente)
+```
+
+## Multi-Subdomínio com SSO
+
+Para apps com subdomínio por tenant (`empresa1.app.com`, `empresa2.app.com`):
+
+```ts
+// detectar tenant pelo subdomínio e redirecionar com callback correto
+const iniciarSSOMultiSubdomain = async (email: string) => {
+  const dominio = email.split('@')[1]
+  const subdominio = window.location.hostname.split('.')[0]  // ex: 'empresa1'
+
+  const { data, error } = await supabase.auth.signInWithSSO({
+    domain: dominio,
+    options: {
+      // callback no subdomínio correto
+      redirectTo: `https://${subdominio}.app.com/auth/callback`,
+    },
+  })
+
+  if (data?.url) window.location.href = data.url
+}
+```
+
+## Regras absolutas
+
+1. **SSO exige Supabase CLI v1.46.4+** — versões anteriores não têm o subcomando `sso`.
+2. **Usar UUID (`auth.uid()`), NUNCA email, como identificador de usuário** — emails não são únicos em ambientes multi-IdP SSO.
+3. **IdP-initiated é incompatível com PKCE** — implementar padrão "bookmark app" (endpoint que inicia SP-initiated).
+4. **RLS RESTRICTIVE para escopo de tenant** — isolamento via `sso_provider_id` deve ser política RESTRICTIVE.
+5. **Sem auto-linking SSO** — nunca assumir que dois registros com mesmo email são o mesmo usuário.
+6. **Usar `@supabase/ssr`, nunca `auth-helpers-nextjs`** — pacote legado descontinuado.
+7. **Validar JWT no servidor com `getClaims()`** — nunca confiar apenas no cliente para verificar identidade SSO.
+
+## Anti-patterns
+
+### Anti-pattern 1: Usar email como chave de usuário SSO
+
+**Errado:**
+```sql
+-- assumindo que email é único entre tenants SSO
+create table public.perfis (
+  email text primary key,  -- ERRADO para SSO
+  dados jsonb
+);
+
+create policy "Usuário vê próprio perfil" on public.perfis
+  as permissive for select to authenticated
+  using (email = (auth.jwt()->>'email'));  -- ERRADO
+```
+
+**Por quê:** se dois IdPs diferentes tiverem um usuário com `joao@empresa.com`, haverá conflito. UUID é o único identificador garantidamente único.
+
+**Certo:**
+```sql
+create table public.perfis (
+  user_id uuid primary key references auth.users(id) on delete cascade,
+  dados   jsonb
+);
+
+create policy "Usuário vê próprio perfil" on public.perfis
+  as permissive for select to authenticated
+  using (user_id = auth.uid());  -- UUID sempre único
+```
+
+### Anti-pattern 2: Assumir auto-linking de contas por email
+
+**Errado:**
+```ts
+// assumindo que se o email já existe, é o mesmo usuário
+const { data: { user } } = await supabase.auth.getUser()
+const perfil = await supabase.from('perfis')
+  .select()
+  .eq('email', user.email)
+  .single()
+// ERRADO: pode retornar perfil de outro usuário SSO com mesmo email
+```
+
+**Por quê:** Supabase **não faz auto-linking** por email em SSO. Cada `signInWithSSO` cria uma identidade nova em `auth.identities`, mesmo que o email já exista.
+
+**Certo:** usar `auth.uid()` como chave de join, nunca email.
+
+### Anti-pattern 3: Esperar IdP-initiated funcionar com PKCE
+
+**Errado:**
+```
+// configurando no Okta:
+// Ícone do app → aponta para ACS URL diretamente
+// ACS URL: https://proj.supabase.co/auth/v1/sso/saml/acs
+// Resultado: erro PKCE validation failed
+```
+
+**Por quê:** quando o IdP inicia, não há `code_verifier` do SP. O PKCE (Proof Key for Code Exchange) exige que o SP inicie o fluxo.
+
+**Certo:** configurar o ícone do app no IdP para apontar ao "bookmark app" (endpoint SP-initiated), não ao ACS URL.
+
+### Anti-pattern 4: Conexão SSO sem validar domínios
+
+**Errado:**
+```bash
+# adicionar SSO sem especificar domains
+supabase sso add \
+  --project-ref abc123 \
+  --type saml \
+  --metadata-url https://idp.exemplo.com/metadata
+  # sem --domains → qualquer um pode tentar signInWithSSO com qualquer domínio
+```
+
+**Por quê:** sem restrição de domínio, `signInWithSSO({ domain: 'qualquer.com' })` pode ser abusado para descoberta de providers.
+
+**Certo:** sempre especificar `--domains` com os domínios exatos de email do tenant:
+```bash
+supabase sso add \
+  --project-ref abc123 \
+  --type saml \
+  --metadata-url https://idp.exemplo.com/metadata \
+  --domains empresa.com.br,empresa.com
+```
+
+## Ver também
+
+- [supabase-auth-methods](../supabase-auth-methods/SKILL.md) — outros providers de autenticação (OAuth, magic link, email)
+- [multi-tenant-rls-hierarchy](../multi-tenant-rls-hierarchy/SKILL.md) — RLS hierárquica para multi-tenant complexo
+- [supabase-auth-ssr](../supabase-auth-ssr/SKILL.md) — padrão `@supabase/ssr` com Next.js e cookies
+- [supabase-custom-claims-rbac](../supabase-custom-claims-rbac/SKILL.md) — RBAC via custom claims combinado com SSO
+- [supabase-mfa](../supabase-mfa/SKILL.md) — MFA adicional para usuários SSO (TOTP sobre aal2)
+- [supabase-sso-saml-architect](../../agents/supabase-sso-saml-architect.md) — agente que configura SSO SAML end-to-end