@luanpdd/kit-mcp 1.31.0 → 1.33.0

package/kit/skills/supabase-auth-hooks/SKILL.md

@@ -0,0 +1,875 @@
+---
+name: supabase-auth-hooks
+description: Use ao implementar Auth Hooks no Supabase — custom access token, send email/SMS, before user created, MFA e password verification hooks.
+---
+
+# Supabase — Auth Hooks
+
+## Quando usar
+
+LLM carrega esta skill quando implementar **Auth Hooks** no Supabase — endpoints que interceptam e modificam o fluxo padrão de autenticação em pontos de execução específicos.
+
+Trigger phrases:
+
+- "auth hook Supabase", "custom access token hook"
+- "send email hook", "send sms hook"
+- "before user created hook", "MFA verification hook"
+- "password verification hook"
+- "Postgres function hook", "HTTP hook Supabase"
+- `custom_access_token_hook`, `supabase_auth_admin`
+- "como bloquear signup por domínio", "como customizar email de auth"
+- "hook para rate-limit de login", "Standard Webhooks Supabase"
+
+## Princípio canônico
+
+Auth Hooks são **endpoints síncronos** que o Supabase Auth invoca em pontos específicos do fluxo de autenticação. O hook recebe um payload JSON, pode modificar o comportamento e retorna um JSON de resposta. Erros retornados pelo hook **bloqueiam** a operação de auth correspondente.
+
+**6 hooks disponíveis:**
+
+| Hook | Disponibilidade | Quando é invocado |
+|------|----------------|-------------------|
+| Before User Created | Free / Pro | Antes de criar novo usuário |
+| Custom Access Token | Free / Pro | Antes de emitir JWT (login + refresh) |
+| Send SMS | Free / Pro | Quando Supabase Auth precisa enviar SMS (OTP, MFA) |
+| Send Email | Free / Pro | Quando Supabase Auth precisa enviar email (confirmação, magic link) |
+| MFA Verification | Teams / Enterprise | Ao verificar código MFA |
+| Password Verification | Teams / Enterprise | Ao verificar senha de login |
+
+**2 tipos de hook:**
+
+| Tipo | URI | Quando usar |
+|------|-----|-------------|
+| **Postgres function** | `pg-functions://postgres/public/<nome_fn>` | Lógica simples, acesso direto ao DB, sem I/O externo |
+| **HTTP endpoint** | URL HTTPS | Lógica complexa, chamada a APIs externas, Edge Functions |
+
+## Modelo de segurança — Postgres Function Hook
+
+A função hook roda com o Postgres role `supabase_auth_admin` — precisa de grants explícitos:
+
+```sql
+-- OBRIGATÓRIO: grants para supabase_auth_admin
+grant usage on schema public to supabase_auth_admin;
+
+grant execute
+  on function public.minha_funcao_hook
+  to supabase_auth_admin;
+
+-- OBRIGATÓRIO: revogar de roles públicos
+revoke execute
+  on function public.minha_funcao_hook
+  from authenticated, anon, public;
+```
+
+**Por quê não usar `security definer`:** prefira grants explícitos — `security definer` faz a função rodar com privilégios do owner (geralmente `postgres`) o que é mais amplo do que necessário. Grants são o mínimo necessário e mais auditáveis.
+
+**Exceção:** se a função precisar acessar tabelas ou schemas que `supabase_auth_admin` não tem permissão, use `security definer` com `set search_path = ''` para evitar injeção via search_path:
+
+```sql
+create or replace function public.custom_access_token_hook(event jsonb)
+returns jsonb
+language plpgsql
+stable
+-- security definer apenas se necessário para acesso a schema restrito
+-- set search_path = ''  -- anti-injeção de schema
+as $$
+  -- implementação
+$$;
+```
+
+## Modelo de segurança — HTTP Hook
+
+Hooks HTTP seguem a especificação **Standard Webhooks** para autenticidade das requisições:
+
+```ts
+// Headers enviados pelo Supabase Auth em cada chamada HTTP ao hook
+// webhook-id: <uuid único por chamada>
+// webhook-timestamp: <unix timestamp em segundos>
+// webhook-signature: v1=<assinatura HMAC-SHA256 base64>
+```
+
+**Verificar assinatura com a lib `standardwebhooks`:**
+
+```ts
+// deno / Edge Function
+import { Webhook } from 'https://esm.sh/standardwebhooks@1.0.0'
+
+const secret = Deno.env.get('SEND_EMAIL_HOOK_SECRET')!
+// formato do secret configurado no Supabase: v1,whsec_<base64-secret>
+
+Deno.serve(async (req) => {
+  const payload = await req.text()
+  const headers = Object.fromEntries(req.headers)
+
+  const wh = new Webhook(secret)
+
+  try {
+    // lança erro se assinatura inválida
+    const event = wh.verify(payload, headers)
+    // processar evento verificado
+    return new Response(JSON.stringify({ success: true }), {
+      headers: { 'Content-Type': 'application/json' },
+    })
+  } catch (err) {
+    // assinatura inválida → rejeitar
+    return new Response(
+      JSON.stringify({ error: { http_code: 401, message: 'Assinatura inválida' } }),
+      { status: 401, headers: { 'Content-Type': 'application/json' } }
+    )
+  }
+})
+```
+
+**Formato do secret:** Supabase gera um secret no formato `v1,whsec_<base64>` — usar exatamente este formato ao instanciar `new Webhook(secret)`.
+
+## Configuração — Dashboard e config.toml
+
+**Via Dashboard (produção):**
+
+1. Acessar `Authentication > Hooks` no Dashboard
+2. Selecionar o tipo de hook (ex: "Custom Access Token")
+3. Escolher tipo: Postgres function ou HTTP
+4. Para Postgres: selecionar a função no dropdown
+5. Para HTTP: digitar a URL + configurar o secret
+6. Salvar
+
+**Via `config.toml` (desenvolvimento local):**
+
+```toml
+# supabase/config.toml
+
+# Custom Access Token Hook (Postgres function)
+[auth.hook.custom_access_token]
+enabled = true
+uri = "pg-functions://postgres/public/custom_access_token_hook"
+
+# Custom Access Token Hook (HTTP — Edge Function local)
+[auth.hook.custom_access_token]
+enabled = true
+uri = "http://localhost:54321/functions/v1/custom-access-token-hook"
+secrets = "v1,whsec_dGVzdHNlY3JldA=="
+
+# Send Email Hook
+[auth.hook.send_email]
+enabled = true
+uri = "http://localhost:54321/functions/v1/send-email-hook"
+secrets = "v1,whsec_dGVzdHNlY3JldA=="
+
+# Send SMS Hook
+[auth.hook.send_sms]
+enabled = true
+uri = "http://localhost:54321/functions/v1/send-sms-hook"
+secrets = "v1,whsec_dGVzdHNlY3JldA=="
+
+# Before User Created Hook
+[auth.hook.before_user_created]
+enabled = true
+uri = "pg-functions://postgres/public/before_user_created_hook"
+
+# MFA Verification Hook (apenas Teams/Enterprise)
+[auth.hook.mfa_verification_attempt]
+enabled = true
+uri = "pg-functions://postgres/public/mfa_verification_hook"
+
+# Password Verification Hook (apenas Teams/Enterprise)
+[auth.hook.password_verification_attempt]
+enabled = true
+uri = "pg-functions://postgres/public/password_verification_hook"
+```
+
+## Error Handling — Status Codes e Retry
+
+**Formato de erro retornado pelo hook:**
+
+```json
+{
+  "error": {
+    "http_code": 403,
+    "message": "Domínio de email não permitido"
+  }
+}
+```
+
+**Comportamento por status code:**
+
+| Status code retornado pelo hook | Comportamento do Supabase Auth |
+|---------------------------------|-------------------------------|
+| `200` / `202` / `204` | Sucesso — continua o fluxo de auth |
+| `400` | Falha permanente — converte em `500` para o cliente (não retry) |
+| `403` | Falha permanente — converte em `500` para o cliente (não retry) |
+| `429` | Rate-limit — **retry** automático (usar header `Retry-After`) |
+| `503` | Serviço indisponível — **retry** automático |
+
+**Respostas retry-able:**
+
+```ts
+// Hook que sinaliza rate-limit com retry
+return new Response(
+  JSON.stringify({ error: { http_code: 429, message: 'Muitas tentativas' } }),
+  {
+    status: 429,
+    headers: {
+      'Content-Type': 'application/json',
+      'Retry-After': '60',  // Supabase Auth vai retentar após 60 segundos
+    },
+  }
+)
+```
+
+**Regra:** TODAS as respostas de hook (sucesso ou erro) devem ter header `Content-Type: application/json`.
+
+## Hook 1 — Custom Access Token
+
+Invocado antes de cada emissão de JWT (login inicial + refresh). Permite injetar claims customizados.
+
+**Input:**
+```json
+{
+  "user_id": "uuid-do-usuario",
+  "claims": {
+    "aal": "aal1",
+    "sub": "uuid-do-usuario",
+    "email": "usuario@empresa.com",
+    "role": "authenticated",
+    "exp": 1704067200,
+    "iat": 1704063600,
+    "iss": "https://proj.supabase.co/auth/v1",
+    "session_id": "uuid-da-sessao",
+    "amr": [{"method": "password", "timestamp": 1704063600}]
+  },
+  "authentication_method": "password"
+}
+```
+
+**Output (modificar claims):**
+```json
+{
+  "claims": {
+    "aal": "aal1",
+    "sub": "uuid-do-usuario",
+    "email": "usuario@empresa.com",
+    "role": "authenticated",
+    "exp": 1704067200,
+    "iat": 1704063600,
+    "iss": "https://proj.supabase.co/auth/v1",
+    "session_id": "uuid-da-sessao",
+    "amr": [{"method": "password", "timestamp": 1704063600}],
+    "user_role": "admin",
+    "org_id": "uuid-da-org"
+  }
+}
+```
+
+**Implementação Postgres canônica (ver skill `supabase-custom-claims-rbac` para pattern completo):**
+
+```sql
+create or replace function public.custom_access_token_hook(event jsonb)
+returns jsonb
+language plpgsql
+stable
+as $$
+  declare
+    claims jsonb;
+    user_role public.app_role;
+  begin
+    select role into user_role
+    from public.user_roles
+    where user_id = (event->>'user_id')::uuid;
+
+    claims := event->'claims';
+
+    claims := jsonb_set(
+      claims,
+      '{user_role}',
+      case when user_role is not null then to_jsonb(user_role) else 'null'::jsonb end
+    );
+
+    return jsonb_set(event, '{claims}', claims);
+  end;
+$$;
+
+-- grants obrigatórios
+grant usage on schema public to supabase_auth_admin;
+grant execute on function public.custom_access_token_hook to supabase_auth_admin;
+revoke execute on function public.custom_access_token_hook from authenticated, anon, public;
+grant all on table public.user_roles to supabase_auth_admin;
+```
+
+**Usos canônicos do Custom Access Token hook:**
+
+- Reduzir tamanho do JWT (omitir claims não necessários)
+- Adicionar claim `user_role`, `org_id`, `plan` ao JWT
+- Restringir login por tipo de autenticação (`authentication_method`)
+- Adicionar claim `is_admin` baseado em SSO provider
+
+```sql
+-- restringir acesso por método de autenticação (ex: SSO apenas para admins)
+create or replace function public.custom_access_token_hook(event jsonb)
+returns jsonb
+language plpgsql
+stable
+as $$
+  declare
+    claims jsonb;
+    auth_method text;
+  begin
+    auth_method := event->>'authentication_method';
+    claims := event->'claims';
+
+    -- adicionar claim que indica se login foi via SSO
+    claims := jsonb_set(claims, '{via_sso}', to_jsonb(auth_method = 'sso/saml'));
+
+    return jsonb_set(event, '{claims}', claims);
+  end;
+$$;
+```
+
+## Hook 2 — Before User Created
+
+Invocado antes de criar um novo usuário. Retornar `error` **rejeita** o signup.
+
+**Input:**
+```json
+{
+  "user": {
+    "id": "uuid-gerado",
+    "email": "novo@dominio.com",
+    "phone": "",
+    "app_metadata": {},
+    "user_metadata": {"nome": "João"},
+    "identities": [],
+    "created_at": "2026-05-19T00:00:00Z",
+    "updated_at": "2026-05-19T00:00:00Z"
+  }
+}
+```
+
+**Bloquear domínios descartáveis:**
+
+```sql
+create or replace function public.before_user_created_hook(event jsonb)
+returns jsonb
+language plpgsql
+stable
+as $$
+  declare
+    email_address text;
+    email_domain  text;
+    dominio_bloqueado bool;
+  begin
+    email_address := event->'user'->>'email';
+    email_domain  := split_part(email_address, '@', 2);
+
+    -- checar em tabela de domínios bloqueados
+    select exists(
+      select 1 from public.blocked_email_domains
+      where domain = lower(email_domain)
+    ) into dominio_bloqueado;
+
+    if dominio_bloqueado then
+      return jsonb_build_object(
+        'error', jsonb_build_object(
+          'http_code', 422,
+          'message', 'Domínio de email não permitido. Use um email corporativo.'
+        )
+      );
+    end if;
+
+    -- retornar event sem modificações (signup permitido)
+    return event;
+  end;
+$$;
+
+-- tabela de domínios bloqueados
+create table public.blocked_email_domains (
+  domain text primary key,
+  motivo text,
+  criado_em timestamptz default now()
+);
+
+-- seed inicial de domínios descartáveis comuns
+insert into public.blocked_email_domains (domain, motivo) values
+  ('mailinator.com', 'Email descartável'),
+  ('guerrillamail.com', 'Email descartável'),
+  ('tempmail.com', 'Email descartável'),
+  ('throwam.com', 'Email descartável'),
+  ('yopmail.com', 'Email descartável');
+
+-- grants
+grant usage on schema public to supabase_auth_admin;
+grant execute on function public.before_user_created_hook to supabase_auth_admin;
+revoke execute on function public.before_user_created_hook from authenticated, anon, public;
+grant select on table public.blocked_email_domains to supabase_auth_admin;
+```
+
+**Bloquear por provider — rejeitar signup via email (apenas SSO permitido):**
+
+```sql
+-- em aplicação B2B que só aceita login via SSO corporativo
+create or replace function public.before_user_created_hook(event jsonb)
+returns jsonb
+language plpgsql
+stable
+as $$
+  declare
+    identities jsonb;
+    tem_sso bool;
+  begin
+    identities := event->'user'->'identities';
+
+    -- checar se tem identidade SSO (provider começa com 'sso:')
+    select exists(
+      select 1 from jsonb_array_elements(identities) as i
+      where (i->>'provider') like 'sso:%'
+    ) into tem_sso;
+
+    if not tem_sso then
+      return jsonb_build_object(
+        'error', jsonb_build_object(
+          'http_code', 403,
+          'message', 'Apenas login via SSO corporativo é permitido.'
+        )
+      );
+    end if;
+
+    return event;
+  end;
+$$;
+```
+
+## Hook 3 — Send SMS
+
+Substitui o envio de SMS do Supabase por provider customizado (Twilio, AWS SNS, Vonage).
+
+**Input:**
+```json
+{
+  "user": { "id": "uuid", "phone": "+5511999999999" },
+  "sms": { "otp": "123456" }
+}
+```
+
+**Edge Function com Twilio:**
+
+```ts
+// supabase/functions/send-sms-hook/index.ts
+import { Webhook } from 'https://esm.sh/standardwebhooks@1.0.0'
+
+const secret = Deno.env.get('SEND_SMS_HOOK_SECRET')!
+const TWILIO_ACCOUNT_SID = Deno.env.get('TWILIO_ACCOUNT_SID')!
+const TWILIO_AUTH_TOKEN = Deno.env.get('TWILIO_AUTH_TOKEN')!
+const TWILIO_FROM = Deno.env.get('TWILIO_FROM_NUMBER')!
+
+Deno.serve(async (req) => {
+  const payload = await req.text()
+  const headers = Object.fromEntries(req.headers)
+
+  // verificar assinatura Standard Webhooks
+  const wh = new Webhook(secret)
+  let event: { user: { phone: string }; sms: { otp: string } }
+  try {
+    event = wh.verify(payload, headers) as typeof event
+  } catch {
+    return new Response(
+      JSON.stringify({ error: { http_code: 401, message: 'Assinatura inválida' } }),
+      { status: 401, headers: { 'Content-Type': 'application/json' } }
+    )
+  }
+
+  const { phone } = event.user
+  const { otp } = event.sms
+
+  // enviar via Twilio
+  const resp = await fetch(
+    `https://api.twilio.com/2010-04-01/Accounts/${TWILIO_ACCOUNT_SID}/Messages.json`,
+    {
+      method: 'POST',
+      headers: {
+        Authorization: `Basic ${btoa(`${TWILIO_ACCOUNT_SID}:${TWILIO_AUTH_TOKEN}`)}`,
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+      body: new URLSearchParams({
+        To: phone,
+        From: TWILIO_FROM,
+        Body: `Seu código de verificação: ${otp}. Válido por 5 minutos.`,
+      }),
+    }
+  )
+
+  if (!resp.ok) {
+    const err = await resp.json()
+    console.error('Erro Twilio:', err)
+    // 503 → Supabase vai retentar
+    return new Response(
+      JSON.stringify({ error: { http_code: 503, message: 'Falha no envio de SMS' } }),
+      { status: 503, headers: { 'Content-Type': 'application/json', 'Retry-After': '30' } }
+    )
+  }
+
+  return new Response(JSON.stringify({}), {
+    headers: { 'Content-Type': 'application/json' },
+  })
+})
+```
+
+## Hook 4 — Send Email
+
+Substitui emails transacionais do Supabase por provider customizado (Resend, SendGrid, AWS SES).
+
+**Input (exemplo para magic link):**
+```json
+{
+  "user": { "id": "uuid", "email": "usuario@empresa.com" },
+  "email_data": {
+    "token": "token-opaque",
+    "token_hash": "hash-do-token",
+    "redirect_to": "https://app.com/auth/callback",
+    "email_action_type": "magic_link",
+    "site_url": "https://app.com",
+    "token_new": "",
+    "token_hash_new": ""
+  }
+}
+```
+
+**Tipos de `email_action_type`:** `signup`, `magic_link`, `recovery`, `invite`, `email_change_new`, `email_change_current`.
+
+**Edge Function com Resend:**
+
+```ts
+// supabase/functions/send-email-hook/index.ts
+import { Webhook } from 'https://esm.sh/standardwebhooks@1.0.0'
+
+const secret = Deno.env.get('SEND_EMAIL_HOOK_SECRET')!
+const RESEND_API_KEY = Deno.env.get('RESEND_API_KEY')!
+
+type EmailActionType = 'signup' | 'magic_link' | 'recovery' | 'invite' |
+  'email_change_new' | 'email_change_current'
+
+function montarConteudo(tipo: EmailActionType, emailData: any): { subject: string; html: string } {
+  const link = `${emailData.site_url}/auth/confirm?token_hash=${emailData.token_hash}&type=${tipo}&next=${emailData.redirect_to}`
+
+  switch (tipo) {
+    case 'magic_link':
+      return {
+        subject: 'Seu link de acesso',
+        html: `<p>Clique <a href="${link}">aqui</a> para acessar. Válido por 1 hora.</p>`,
+      }
+    case 'signup':
+      return {
+        subject: 'Confirme seu email',
+        html: `<p>Bem-vindo! <a href="${link}">Confirme seu email</a> para começar.</p>`,
+      }
+    case 'recovery':
+      return {
+        subject: 'Recuperação de senha',
+        html: `<p><a href="${link}">Redefina sua senha</a>. Válido por 1 hora.</p>`,
+      }
+    default:
+      return {
+        subject: 'Ação necessária',
+        html: `<p><a href="${link}">Clique aqui</a> para continuar.</p>`,
+      }
+  }
+}
+
+Deno.serve(async (req) => {
+  const payload = await req.text()
+  const headers = Object.fromEntries(req.headers)
+
+  const wh = new Webhook(secret)
+  let event: { user: { email: string }; email_data: any }
+  try {
+    event = wh.verify(payload, headers) as typeof event
+  } catch {
+    return new Response(
+      JSON.stringify({ error: { http_code: 401, message: 'Assinatura inválida' } }),
+      { status: 401, headers: { 'Content-Type': 'application/json' } }
+    )
+  }
+
+  const { email } = event.user
+  const { email_action_type, ...emailData } = event.email_data
+  const { subject, html } = montarConteudo(email_action_type, { email_action_type, ...emailData })
+
+  const resp = await fetch('https://api.resend.com/emails', {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${RESEND_API_KEY}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      from: 'no-reply@empresa.com',
+      to: [email],
+      subject,
+      html,
+    }),
+  })
+
+  if (!resp.ok) {
+    return new Response(
+      JSON.stringify({ error: { http_code: 503, message: 'Falha no envio de email' } }),
+      { status: 503, headers: { 'Content-Type': 'application/json', 'Retry-After': '60' } }
+    )
+  }
+
+  return new Response(JSON.stringify({}), {
+    headers: { 'Content-Type': 'application/json' },
+  })
+})
+```
+
+## Hook 5 — MFA Verification (Teams/Enterprise)
+
+Rate-limit customizado para tentativas de verificação MFA. Roda a cada `mfa.verify()`.
+
+**Input:**
+```json
+{
+  "factor_id": "uuid-do-fator",
+  "factor_type": "totp",
+  "user_id": "uuid-do-usuario",
+  "valid": true
+}
+```
+
+**Output:**
+```json
+{
+  "decision": "continue",
+  "message": ""
+}
+```
+
+```sql
+-- rate-limit: máximo 5 tentativas erradas em 15 minutos
+create table public.mfa_attempt_log (
+  user_id     uuid not null references auth.users(id) on delete cascade,
+  factor_id   uuid not null,
+  tentativa   timestamptz not null default now(),
+  sucesso     boolean not null
+);
+
+create index on public.mfa_attempt_log (user_id, tentativa);
+
+create or replace function public.mfa_verification_hook(event jsonb)
+returns jsonb
+language plpgsql
+as $$
+  declare
+    user_id_val   uuid;
+    factor_id_val uuid;
+    valida        bool;
+    tentativas_erradas int;
+  begin
+    user_id_val   := (event->>'user_id')::uuid;
+    factor_id_val := (event->>'factor_id')::uuid;
+    valida        := (event->>'valid')::boolean;
+
+    -- checar tentativas erradas nos últimos 15 minutos
+    select count(*) into tentativas_erradas
+    from public.mfa_attempt_log
+    where user_id = user_id_val
+      and factor_id = factor_id_val
+      and sucesso = false
+      and tentativa > now() - interval '15 minutes';
+
+    -- logar tentativa atual
+    insert into public.mfa_attempt_log (user_id, factor_id, sucesso)
+    values (user_id_val, factor_id_val, valida);
+
+    if tentativas_erradas >= 5 then
+      return jsonb_build_object(
+        'decision', 'reject',
+        'message', 'Muitas tentativas incorretas. Aguarde 15 minutos.'
+      );
+    end if;
+
+    return jsonb_build_object('decision', 'continue', 'message', '');
+  end;
+$$;
+
+grant usage on schema public to supabase_auth_admin;
+grant execute on function public.mfa_verification_hook to supabase_auth_admin;
+revoke execute on function public.mfa_verification_hook from authenticated, anon, public;
+grant all on table public.mfa_attempt_log to supabase_auth_admin;
+```
+
+## Hook 6 — Password Verification (Teams/Enterprise)
+
+Bloquear login após N tentativas erradas de senha.
+
+**Input:**
+```json
+{
+  "user_id": "uuid-do-usuario",
+  "valid": false
+}
+```
+
+```sql
+create or replace function public.password_verification_hook(event jsonb)
+returns jsonb
+language plpgsql
+as $$
+  declare
+    uid            uuid;
+    valida         bool;
+    erros_recentes int;
+  begin
+    uid    := (event->>'user_id')::uuid;
+    valida := (event->>'valid')::boolean;
+
+    -- logar tentativa
+    insert into public.login_attempt_log (user_id, sucesso)
+    values (uid, valida);
+
+    -- contar erros nos últimos 30 minutos (apenas se tentativa inválida)
+    if not valida then
+      select count(*) into erros_recentes
+      from public.login_attempt_log
+      where user_id = uid
+        and sucesso = false
+        and tentativa > now() - interval '30 minutes';
+
+      if erros_recentes >= 10 then
+        return jsonb_build_object(
+          'decision', 'reject',
+          'message', 'Conta temporariamente bloqueada. Tente novamente em 30 minutos.'
+        );
+      end if;
+    end if;
+
+    return jsonb_build_object('decision', 'continue', 'message', '');
+  end;
+$$;
+
+create table public.login_attempt_log (
+  id        bigint generated by default as identity primary key,
+  user_id   uuid not null references auth.users(id) on delete cascade,
+  sucesso   boolean not null,
+  tentativa timestamptz default now()
+);
+create index on public.login_attempt_log (user_id, tentativa);
+
+grant usage on schema public to supabase_auth_admin;
+grant execute on function public.password_verification_hook to supabase_auth_admin;
+revoke execute on function public.password_verification_hook from authenticated, anon, public;
+grant all on table public.login_attempt_log to supabase_auth_admin;
+```
+
+## Regras absolutas
+
+1. **SEMPRE `grant execute` ao `supabase_auth_admin`** — sem este grant, hook Postgres falha silenciosamente; JWT é emitido sem modificações.
+2. **SEMPRE `revoke execute` de `authenticated`, `anon`, `public`** — sem isso, qualquer cliente pode invocar a função diretamente.
+3. **Hooks HTTP devem verificar assinatura Standard Webhooks** — usar `standardwebhooks` com o secret configurado. Nunca processar payload sem verificação.
+4. **Evitar `security definer` desnecessariamente** — prefira grants explícitos; `security definer` amplia o acesso mais do que necessário.
+5. **TODAS as respostas precisam `Content-Type: application/json`** — Supabase Auth rejeita respostas sem este header.
+6. **Hook deve ser rápido (< 10ms idealmente)** — roda a cada login e refresh; query lenta degrada latência de auth de toda a aplicação.
+7. **Hooks MFA/Password Verification são Teams/Enterprise only** — verificar plano antes de implementar.
+
+## Anti-patterns
+
+### Anti-pattern 1: Esquecer grants ao supabase_auth_admin
+
+**Errado:**
+```sql
+create or replace function public.custom_access_token_hook(event jsonb)
+returns jsonb language plpgsql stable as $$
+  -- implementação aqui
+$$;
+-- sem GRANT EXECUTE TO supabase_auth_admin
+-- sem REVOKE de anon/authenticated
+```
+
+**Por quê:** Auth hook falha silenciosamente. O JWT é gerado **sem** as modificações do hook — claims customizados não aparecem. Difícil de debugar pois não há erro explícito.
+
+**Certo:**
+```sql
+-- SEMPRE após criar a função
+grant usage on schema public to supabase_auth_admin;
+grant execute on function public.custom_access_token_hook to supabase_auth_admin;
+revoke execute on function public.custom_access_token_hook from authenticated, anon, public;
+```
+
+### Anti-pattern 2: Não verificar assinatura do webhook HTTP
+
+**Errado:**
+```ts
+Deno.serve(async (req) => {
+  const event = await req.json()  // ERRADO: aceitar sem verificar assinatura
+  // processar event...
+})
+```
+
+**Por quê:** qualquer requisição HTTP pode acionar o hook — atacante pode forjar eventos de auth e manipular JWTs, criar usuários, etc.
+
+**Certo:** sempre verificar com `standardwebhooks`:
+```ts
+const wh = new Webhook(secret)
+const event = wh.verify(payload, headers)  // lança erro se inválido
+```
+
+### Anti-pattern 3: Hook com query custosa (JOINs, N+1)
+
+**Errado:**
+```sql
+create or replace function public.custom_access_token_hook(event jsonb)
+returns jsonb language plpgsql stable as $$
+  declare claims jsonb;
+  begin
+    claims := event->'claims';
+    -- query com múltiplos JOINs — roda em CADA login e refresh
+    select jsonb_build_object(
+      'org_name', o.name,
+      'plan', s.plan,
+      'feature_flags', ff.flags
+    ) into ...
+    from auth.users u
+      join public.organizations o on u.raw_user_meta_data->>'org_id' = o.id::text
+      join public.subscriptions s on o.id = s.org_id
+      join public.feature_flags ff on s.plan = ff.plan
+    where u.id = (event->>'user_id')::uuid;
+    -- ...
+  end;
+$$;
+```
+
+**Por quê:** hook roda em cada login E cada refresh de JWT. Query com JOINs pode adicionar 50-200ms em cada operação de auth — inaceitável em produção.
+
+**Certo:** denormalizar dados na tabela de roles/perfis; hook faz query simples em única tabela:
+```sql
+-- tabela denormalizada: user_profile com tudo necessário
+select org_name, plan, feature_flags
+into user_data
+from public.user_profiles
+where user_id = (event->>'user_id')::uuid;
+```
+
+### Anti-pattern 4: Usar `security definer` desnecessariamente
+
+**Errado:**
+```sql
+create or replace function public.before_user_created_hook(event jsonb)
+returns jsonb
+language plpgsql
+security definer   -- DESNECESSÁRIO se grants explícitos suficientes
+as $$
+  -- ...
+$$;
+```
+
+**Por quê:** `security definer` faz a função rodar com privilégios do owner (`postgres`) — acesso irrestrito a todos os schemas e tabelas. Risco de path injection e acesso não intencional.
+
+**Certo:** grants explícitos ao `supabase_auth_admin` para tabelas específicas + sem `security definer`:
+```sql
+grant select on table public.blocked_email_domains to supabase_auth_admin;
+-- sem security definer na função
+```
+
+## Ver também
+
+- [supabase-custom-claims-rbac](../supabase-custom-claims-rbac/SKILL.md) — `custom_access_token_hook` completo com RBAC
+- [supabase-edge-functions-auth](../supabase-edge-functions-auth/SKILL.md) — autenticação e segurança em Edge Functions
+- [supabase-mfa](../supabase-mfa/SKILL.md) — MFA TOTP e Phone; MFA Verification Hook para rate-limit
+- [supabase-rls-policies](../supabase-rls-policies/SKILL.md) — políticas RLS que consomem claims do `custom_access_token_hook`
+- [supabase-auth-hook-writer](../../agents/supabase-auth-hook-writer.md) — agente que escreve Auth Hooks com grants corretos e testes