@luanpdd/kit-mcp 1.31.0 → 1.33.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (30) hide show
  1. package/README.md +1 -1
  2. package/kit/COMPATIBILITY.md +5 -0
  3. package/kit/agents/designer-ui.md +216 -0
  4. package/kit/agents/supabase-auth-bootstrapper.md +15 -1
  5. package/kit/agents/supabase-auth-hook-writer.md +418 -0
  6. package/kit/agents/supabase-mfa-implementer.md +439 -0
  7. package/kit/agents/supabase-oauth-server-implementer.md +507 -0
  8. package/kit/agents/supabase-social-auth-implementer.md +451 -0
  9. package/kit/agents/supabase-sso-saml-architect.md +549 -0
  10. package/kit/commands/supabase.md +21 -1
  11. package/kit/file-manifest.json +29 -6
  12. package/kit/skills/supabase-auth-hardening/SKILL.md +674 -0
  13. package/kit/skills/supabase-auth-hooks/SKILL.md +875 -0
  14. package/kit/skills/supabase-auth-methods/SKILL.md +486 -0
  15. package/kit/skills/supabase-auth-sessions/SKILL.md +579 -0
  16. package/kit/skills/supabase-auth-ssr/SKILL.md +60 -14
  17. package/kit/skills/supabase-enterprise-sso-saml/SKILL.md +545 -0
  18. package/kit/skills/supabase-jwt-signing-keys/SKILL.md +399 -0
  19. package/kit/skills/supabase-mfa/SKILL.md +488 -0
  20. package/kit/skills/supabase-oauth-server/SKILL.md +537 -0
  21. package/kit/skills/supabase-social-oauth/SKILL.md +480 -0
  22. package/kit/skills/supabase-third-party-auth/SKILL.md +450 -0
  23. package/kit/skills/ui-anti-padroes-ia/SKILL.md +261 -0
  24. package/kit/skills/ui-contexto-produto/SKILL.md +248 -0
  25. package/kit/skills/ui-cor-estrategia/SKILL.md +213 -0
  26. package/kit/skills/ui-critica-auditoria/SKILL.md +260 -0
  27. package/kit/skills/ui-motion-funcional/SKILL.md +264 -0
  28. package/kit/skills/ui-ritmo-espacial/SKILL.md +259 -0
  29. package/kit/skills/ui-tipografia/SKILL.md +211 -0
  30. package/package.json +1 -1
@@ -0,0 +1,674 @@
1
+ ---
2
+ name: supabase-auth-hardening
3
+ description: Use ao configurar SMTP customizado, templates de email, redirect URLs, rate limits, CAPTCHA, segurança de senha e audit logs de autenticação no Supabase.
4
+ ---
5
+
6
+ # Supabase — Hardening de Autenticação (Config, SMTP, Rate Limits, CAPTCHA)
7
+
8
+ ## Quando usar
9
+
10
+ LLM carrega esta skill quando o projeto precisar **endurecer a segurança de autenticação** do Supabase — configurando SMTP para produção, protegendo contra bots e abuso, gerenciando email templates, redirect URLs seguras ou habilitando proteção de senhas.
11
+
12
+ Trigger phrases:
13
+
14
+ - "custom SMTP Supabase", "email template Supabase"
15
+ - "redirect URLs Supabase", "rate limit auth"
16
+ - "CAPTCHA Supabase", "hCaptcha", "Turnstile"
17
+ - "password security Supabase", "leaked password protection"
18
+ - "auth audit logs", "signup abuse Supabase"
19
+ - "email prefetching problema", "OTP email Supabase"
20
+
21
+ ## Princípio canônico
22
+
23
+ Auth hardening em Supabase tem **4 camadas complementares**:
24
+
25
+ 1. **Config básica** — controlar quem pode se registrar, confirmar email, sessões anônimas
26
+ 2. **SMTP + email templates** — garantir entregabilidade e segurança dos emails de auth
27
+ 3. **Rate limits + CAPTCHA** — proteger contra abuso automatizado e bots
28
+ 4. **Password security + audit** — senhas fortes, proteção contra vazamentos, rastreabilidade
29
+
30
+ Nenhuma camada substitui as outras — produção exige todas as quatro.
31
+
32
+ ## Config geral de autenticação
33
+
34
+ ### Via Dashboard
35
+
36
+ `Authentication > Providers > Email`
37
+
38
+ ### Via `config.toml`
39
+
40
+ ```toml
41
+ [auth]
42
+ # Permitir ou bloquear novos registros (false = apenas usuários existentes)
43
+ enable_signup = true
44
+
45
+ # Exigir confirmação de email antes de liberar acesso
46
+ double_confirm_email_change = true
47
+
48
+ # Sessões anônimas (usuários sem login — útil para carrinhos, rascunhos)
49
+ enable_anonymous_sign_ins = false
50
+
51
+ # Permitir que usuários vinculem múltiplos provedores de auth manualmente
52
+ enable_manual_linking = false
53
+
54
+ # Expiração do access token (padrão: 3600 = 1h)
55
+ jwt_expiry = 3600
56
+
57
+ # Refresh token não expira automaticamente
58
+ enable_refresh_token_rotation = true
59
+ refresh_token_reuse_interval = 10 # janela de reuso em segundos (graceful)
60
+ ```
61
+
62
+ ### Configurações recomendadas por ambiente
63
+
64
+ | Config | Desenvolvimento | Produção |
65
+ |--------|----------------|---------|
66
+ | `enable_signup` | `true` | Depende do modelo (invite-only = `false`) |
67
+ | `double_confirm_email_change` | `false` | `true` |
68
+ | `enable_anonymous_sign_ins` | `true` | Conforme necessidade |
69
+ | `enable_refresh_token_rotation` | `true` | `true` (obrigatório) |
70
+
71
+ ## Email Templates
72
+
73
+ ### Tipos de templates
74
+
75
+ **Emails de autenticação** (enviados via SMTP configurado):
76
+ - `confirm_signup` — confirmação de email no cadastro
77
+ - `invite` — convite de usuário por admin
78
+ - `magic_link` — link mágico de login
79
+ - `change_email_address` — confirmação de troca de email
80
+ - `reset_password` — redefinição de senha
81
+
82
+ **Emails de notificação de segurança** (sempre enviados, não customizáveis via template):
83
+ - Alertas de login de novo dispositivo
84
+ - Notificações de MFA configurado/removido
85
+
86
+ ### Variáveis disponíveis nos templates
87
+
88
+ | Variável | Descrição |
89
+ |----------|-----------|
90
+ | `{{ .ConfirmationURL }}` | URL completa de confirmação (inclui token) |
91
+ | `{{ .Token }}` | OTP de 6 dígitos (para fluxo OTP, evita prefetching) |
92
+ | `{{ .TokenHash }}` | Hash do token (fluxo PKCE — não expõe token direto) |
93
+ | `{{ .SiteURL }}` | URL base do site (configurada em Auth settings) |
94
+ | `{{ .RedirectTo }}` | URL de redirect passada pelo cliente |
95
+ | `{{ .Email }}` | Email do usuário |
96
+ | `{{ .NewEmail }}` | Novo email (para change_email_address) |
97
+ | `{{ .Data }}` | Metadados adicionais (objeto JSON) |
98
+
99
+ ### Problema crítico: Email Prefetching
100
+
101
+ Alguns serviços de email corporativos (Outlook, Exchange, scanners de segurança) **acessam automaticamente links nos emails** para verificar malware — consumindo o token de confirmação antes do usuário clicar.
102
+
103
+ **Errado (vulnerável a prefetching):**
104
+ ```html
105
+ <!-- Template padrão com link direto -->
106
+ <p>Confirme seu cadastro:</p>
107
+ <a href="{{ .ConfirmationURL }}">Confirmar email</a>
108
+ <!-- Scanner consome o link antes do usuário → usuário vê "link expirado" -->
109
+ ```
110
+
111
+ **Solução A — OTP (recomendado para flows sensíveis):**
112
+ ```html
113
+ <!-- Template com OTP de 6 dígitos — scanner não "usa" um número -->
114
+ <p>Seu código de confirmação: <strong>{{ .Token }}</strong></p>
115
+ <p>Digite este código na tela de confirmação do aplicativo.</p>
116
+ ```
117
+
118
+ ```ts
119
+ // Frontend — verificar OTP
120
+ const { data, error } = await supabase.auth.verifyOtp({
121
+ email: userEmail,
122
+ token: otpDigitado, // código 6 dígitos do email
123
+ type: 'signup', // 'signup' | 'magiclink' | 'recovery' | 'email_change'
124
+ })
125
+ ```
126
+
127
+ **Solução B — Link customizado com token_hash (PKCE flow):**
128
+ ```html
129
+ <!-- Token hash não é o token real — scanner não consegue usar -->
130
+ <a href="{{ .SiteURL }}/confirm?token_hash={{ .TokenHash }}&type=signup&next={{ .RedirectTo }}">
131
+ Confirmar email
132
+ </a>
133
+ ```
134
+
135
+ ```ts
136
+ // Rota /confirm — trocar token_hash pelo token real
137
+ export async function GET(request: Request) {
138
+ const url = new URL(request.url)
139
+ const tokenHash = url.searchParams.get('token_hash')
140
+ const type = url.searchParams.get('type') as any
141
+
142
+ if (tokenHash && type) {
143
+ const { error } = await supabase.auth.verifyOtp({ token_hash: tokenHash, type })
144
+ if (!error) redirect(url.searchParams.get('next') ?? '/')
145
+ }
146
+
147
+ redirect('/auth/error?message=link-invalido')
148
+ }
149
+ ```
150
+
151
+ ### Customizar templates com Go Templates
152
+
153
+ Templates suportam sintaxe Go Template para lógica condicional:
154
+
155
+ ```html
156
+ {{ if eq .Data.plan "enterprise" }}
157
+ <p>Bem-vindo ao plano Enterprise! Seu gerente de conta entrará em contato.</p>
158
+ {{ else }}
159
+ <p>Bem-vindo! Comece sua avaliação gratuita de 14 dias.</p>
160
+ {{ end }}
161
+
162
+ <p>Confirme seu email:</p>
163
+ <a href="{{ .ConfirmationURL }}">Confirmar</a>
164
+ ```
165
+
166
+ ### Management API para templates
167
+
168
+ ```ts
169
+ // Atualizar template via API (service_role)
170
+ const { error } = await supabaseAdmin.from('_supabase_auth_templates').upsert({
171
+ template_type: 'confirm_signup',
172
+ subject: 'Confirme seu cadastro em {{ .SiteURL }}',
173
+ content: '<html>...</html>',
174
+ })
175
+ ```
176
+
177
+ ## Custom SMTP
178
+
179
+ ### Por que SMTP customizado é obrigatório em produção
180
+
181
+ O SMTP padrão do Supabase:
182
+ - **Só envia para endereços da equipe do projeto** — não envia para usuários externos
183
+ - **Rate limit muito baixo** — inadequado para produção
184
+ - **Não customizável** — domínio `noreply@mail.supabase.io`, sem DKIM/DMARC
185
+
186
+ **Provedores recomendados por caso de uso:**
187
+
188
+ | Provedor | Melhor para |
189
+ |----------|------------|
190
+ | Resend | DX moderno, APIs React Email |
191
+ | AWS SES | Escala, custo baixo, ecossistema AWS |
192
+ | Postmark | Alta entregabilidade transacional |
193
+ | SendGrid | Volume alto, analytics |
194
+ | Mailgun | Europeu, GDPR |
195
+
196
+ ### Configurar via `config.toml`
197
+
198
+ ```toml
199
+ [auth.email.smtp]
200
+ enabled = true
201
+ host = "smtp.resend.com"
202
+ port = 465
203
+ user = "resend"
204
+ pass = "env(SMTP_PASSWORD)" # env var — nunca valor direto em config.toml
205
+ admin_email = "noreply@meuapp.com"
206
+ sender_name = "Meu App"
207
+ ```
208
+
209
+ ### Configurar via Dashboard
210
+
211
+ `Authentication > Providers > Email > Custom SMTP` → preencher host, port, user, password.
212
+
213
+ ### Checklist de configuração de email
214
+
215
+ ```
216
+ ☐ SPF record — "v=spf1 include:_spf.resend.com ~all"
217
+ ☐ DKIM record — chave pública no DNS (obtida no provedor)
218
+ ☐ DMARC policy — "v=DMARC1; p=quarantine; rua=mailto:dmarc@meuapp.com"
219
+ ☐ Domínio de envio verificado no provedor
220
+ ☐ Endereço de reply-to configurado
221
+ ☐ Emails de auth separados dos emails de marketing (subdomínios diferentes)
222
+ ☐ Testar entregabilidade com mail-tester.com
223
+ ```
224
+
225
+ ### Separar emails de auth dos de marketing
226
+
227
+ **Problema:** usar o mesmo domínio/IP para emails transacionais (auth) e marketing (newsletters) faz com que reclamações de spam do marketing afetem a entregabilidade de emails de auth.
228
+
229
+ **Certo:** usar subdomínio dedicado para auth:
230
+ - Auth: `noreply@auth.meuapp.com` (subdomínio `auth.`)
231
+ - Marketing: `news@meuapp.com` (domínio principal)
232
+
233
+ ### Mitigação de abuso de SMTP
234
+
235
+ ```toml
236
+ [auth.email]
237
+ # Rate limit de emails por hora por IP
238
+ max_frequency = "1m" # mínimo 1 minuto entre emails para o mesmo endereço
239
+ ```
240
+
241
+ Combinado com CAPTCHA (ver abaixo) e rate limits de endpoint.
242
+
243
+ ## Redirect URLs
244
+
245
+ ### Site URL
246
+
247
+ A Site URL é o redirect padrão quando nenhum `redirectTo` é especificado:
248
+
249
+ ```toml
250
+ [auth]
251
+ site_url = "https://meuapp.com" # PRODUÇÃO — nunca deixar como localhost
252
+ # site_url = "http://localhost:3000" # só em desenvolvimento local
253
+ ```
254
+
255
+ **Erro crítico:** Site URL apontando para `localhost` em produção — usuários são redirecionados para localhost após login/confirmação.
256
+
257
+ ### Allowlist de URLs
258
+
259
+ ```toml
260
+ [auth]
261
+ additional_redirect_urls = [
262
+ "https://meuapp.com",
263
+ "https://app.meuapp.com",
264
+ "https://meuapp.vercel.app",
265
+ ]
266
+ ```
267
+
268
+ ### Wildcards em redirect URLs
269
+
270
+ | Wildcard | Comportamento |
271
+ |----------|--------------|
272
+ | `*` | Qualquer string sem `/` (mesmo segmento) |
273
+ | `**` | Qualquer string incluindo `/` (multi-segmento) |
274
+ | `?` | Um único caractere |
275
+
276
+ ```toml
277
+ additional_redirect_urls = [
278
+ # URLs de preview do Vercel (branch deploys)
279
+ "https://meuapp-*.vercel.app", # * cobre apenas um segmento
280
+ "https://meuapp-git-*.vercel.app/**", # ** cobre qualquer path após
281
+
282
+ # Netlify
283
+ "https://*--meuapp.netlify.app",
284
+
285
+ # Mobile deep links
286
+ "meuapp://auth/callback",
287
+ ]
288
+ ```
289
+
290
+ **Atenção com wildcards:** wildcards muito amplos (ex: `https://*`) são vetores de open redirect. Ser específico ao máximo — usar o domínio base como prefixo do wildcard.
291
+
292
+ ### Passando `redirectTo` no código
293
+
294
+ ```ts
295
+ // Signup com redirect customizado
296
+ const { error } = await supabase.auth.signUp({
297
+ email: 'user@exemplo.com',
298
+ password: 'senha123',
299
+ options: {
300
+ emailRedirectTo: 'https://meuapp.com/onboarding', // deve estar na allowlist
301
+ },
302
+ })
303
+
304
+ // Magic link com redirect customizado
305
+ const { error } = await supabase.auth.signInWithOtp({
306
+ email: 'user@exemplo.com',
307
+ options: {
308
+ emailRedirectTo: 'https://meuapp.com/dashboard',
309
+ },
310
+ })
311
+ ```
312
+
313
+ ## Rate Limits
314
+
315
+ ### Algoritmo Token Bucket
316
+
317
+ Supabase usa token bucket para rate limiting de auth:
318
+
319
+ ```
320
+ Capacidade: N tokens
321
+ Reabastecimento: K tokens por período
322
+ Request consome 1 token
323
+ Quando tokens = 0: requisição rejeitada com 429
324
+ ```
325
+
326
+ ### Limites padrão por endpoint
327
+
328
+ | Endpoint | Limite padrão | Customizável |
329
+ |----------|--------------|--------------|
330
+ | `/auth/v1/signup` | 30/hora por IP | Sim (Pro+) |
331
+ | `/auth/v1/token` (signIn) | 30/hora por IP | Sim (Pro+) |
332
+ | `/auth/v1/otp` (magic link) | 30/hora por IP | Sim (Pro+) |
333
+ | `/auth/v1/recover` (reset password) | 30/hora por IP | Sim (Pro+) |
334
+ | `/auth/v1/user` | 30/hora por IP | Sim (Pro+) |
335
+ | `/auth/v1/resend` | 3/hora por email | Não |
336
+
337
+ ### IP Forwarding com `Sb-Forwarded-For`
338
+
339
+ Em deployments atrás de proxy/load balancer, o IP real do cliente pode ser mascarado. Use o header `Sb-Forwarded-For` para informar o IP real ao Supabase:
340
+
341
+ ```ts
342
+ // Edge Function ou backend — repassar IP real para rate limiting
343
+ const response = await fetch(`${SUPABASE_URL}/auth/v1/signup`, {
344
+ method: 'POST',
345
+ headers: {
346
+ 'Content-Type': 'application/json',
347
+ 'apikey': SUPABASE_ANON_KEY,
348
+ 'Sb-Forwarded-For': request.headers.get('x-forwarded-for') ?? '',
349
+ // ATENÇÃO: 'Sb-Forwarded-For' só é respeitado com service_role key
350
+ 'Authorization': `Bearer ${SUPABASE_SERVICE_ROLE_KEY}`,
351
+ },
352
+ body: JSON.stringify({ email, password }),
353
+ })
354
+ ```
355
+
356
+ **Requisito de segurança:** o header `Sb-Forwarded-For` é aceito apenas quando a requisição usa `service_role` key. Com `anon` key, o header é ignorado (prevenção de spoofing).
357
+
358
+ ## CAPTCHA
359
+
360
+ ### Provedores suportados
361
+
362
+ | Provedor | Tipo | Privacy |
363
+ |----------|------|---------|
364
+ | **hCaptcha** | Challenges visuais | Maior privacidade |
365
+ | **Cloudflare Turnstile** | Invisível (comportamental) | Privacy-first |
366
+
367
+ ### Habilitar via Dashboard
368
+
369
+ `Authentication > Security > CAPTCHA protection` → Selecionar provedor → Colar Site Key.
370
+
371
+ ### Habilitar via `config.toml`
372
+
373
+ ```toml
374
+ [auth.captcha]
375
+ enabled = true
376
+ provider = "turnstile" # ou "hcaptcha"
377
+ secret = "env(CAPTCHA_SECRET_KEY)"
378
+ ```
379
+
380
+ ### Componente frontend (React)
381
+
382
+ ```tsx
383
+ // components/AuthForm.tsx — com Turnstile
384
+ import { Turnstile } from '@marsidev/react-turnstile'
385
+
386
+ export function SignUpForm() {
387
+ const [captchaToken, setCaptchaToken] = useState<string>('')
388
+ const supabase = createClient()
389
+
390
+ async function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
391
+ e.preventDefault()
392
+ const formData = new FormData(e.currentTarget)
393
+
394
+ const { error } = await supabase.auth.signUp({
395
+ email: formData.get('email') as string,
396
+ password: formData.get('password') as string,
397
+ options: {
398
+ captchaToken, // token obtido do widget
399
+ },
400
+ })
401
+
402
+ if (error) console.error(error.message)
403
+ }
404
+
405
+ return (
406
+ <form onSubmit={handleSubmit}>
407
+ <input name="email" type="email" required />
408
+ <input name="password" type="password" required />
409
+
410
+ <Turnstile
411
+ siteKey={process.env.NEXT_PUBLIC_TURNSTILE_SITE_KEY!}
412
+ onSuccess={setCaptchaToken}
413
+ onExpire={() => setCaptchaToken('')}
414
+ />
415
+
416
+ <button type="submit" disabled={!captchaToken}>Criar conta</button>
417
+ </form>
418
+ )
419
+ }
420
+ ```
421
+
422
+ ### CAPTCHA em outros endpoints
423
+
424
+ ```ts
425
+ // Magic link com CAPTCHA
426
+ const { error } = await supabase.auth.signInWithOtp({
427
+ email,
428
+ options: { captchaToken },
429
+ })
430
+
431
+ // Reset de senha com CAPTCHA
432
+ const { error } = await supabase.auth.resetPasswordForEmail(email, {
433
+ captchaToken,
434
+ redirectTo: 'https://meuapp.com/reset',
435
+ })
436
+ ```
437
+
438
+ ### hCaptcha — Alternativa com maior privacidade
439
+
440
+ ```tsx
441
+ import HCaptcha from '@hcaptcha/react-hcaptcha'
442
+
443
+ function SignInForm() {
444
+ const captchaRef = useRef<HCaptcha>(null)
445
+ const [captchaToken, setCaptchaToken] = useState<string>('')
446
+
447
+ return (
448
+ <form>
449
+ <HCaptcha
450
+ sitekey={process.env.NEXT_PUBLIC_HCAPTCHA_SITE_KEY!}
451
+ ref={captchaRef}
452
+ onVerify={setCaptchaToken}
453
+ onExpire={() => setCaptchaToken('')}
454
+ />
455
+ <button type="submit" disabled={!captchaToken}>Entrar</button>
456
+ </form>
457
+ )
458
+ }
459
+ ```
460
+
461
+ ## Password Security
462
+
463
+ ### Configurar políticas de senha
464
+
465
+ ```toml
466
+ [auth.password]
467
+ # Comprimento mínimo (padrão: 6, recomendado: 12+)
468
+ min_length = 12
469
+
470
+ # Exigir caracteres específicos
471
+ require_uppercase = true # pelo menos 1 maiúscula
472
+ require_lowercase = true # pelo menos 1 minúscula
473
+ require_numbers = true # pelo menos 1 número
474
+ require_special_characters = true # pelo menos 1 especial
475
+
476
+ # Proteção contra senhas vazadas (HaveIBeenPwned) — Pro+
477
+ check_breached_passwords = true
478
+ ```
479
+
480
+ ### Leaked Password Protection (HaveIBeenPwned)
481
+
482
+ ```toml
483
+ [auth.password]
484
+ check_breached_passwords = true # rejeita senhas em listas de vazamento conhecidas
485
+ ```
486
+
487
+ Como funciona: a senha é verificada via k-Anonymity contra a API HaveIBeenPwned — apenas os 5 primeiros caracteres do hash SHA-1 são enviados (a senha nunca sai do ambiente).
488
+
489
+ ### Exigir reautenticação antes de trocar senha
490
+
491
+ ```ts
492
+ // 1. Solicitar verificação de identidade (envia email/SMS)
493
+ const { error } = await supabase.auth.reauthenticate()
494
+
495
+ // 2. Verificar código recebido
496
+ const { error } = await supabase.auth.verifyOtp({
497
+ email: userEmail,
498
+ token: codigoDigitado,
499
+ type: 'reauthentication',
500
+ })
501
+
502
+ // 3. Após verificação, atualizar senha
503
+ const { error } = await supabase.auth.updateUser({
504
+ password: novaSenha,
505
+ })
506
+ ```
507
+
508
+ ### Exigir senha atual ao trocar senha
509
+
510
+ ```ts
511
+ // Passar a senha atual junto da nova senha para garantir autenticidade
512
+ const { error } = await supabase.auth.updateUser({
513
+ password: novaSenha,
514
+ // current_password evita ataques de session fixation
515
+ // (disponível em versões recentes do @supabase/supabase-js)
516
+ })
517
+ ```
518
+
519
+ ## Audit Logs
520
+
521
+ ### Tabela `auth.audit_log_entries`
522
+
523
+ ```sql
524
+ -- Ver últimas ações de auth
525
+ select
526
+ created_at,
527
+ payload->>'action' as action,
528
+ payload->>'actor_id' as user_id,
529
+ payload->>'actor_username' as email,
530
+ payload->>'ip_address' as ip,
531
+ payload->>'traits' as traits
532
+ from auth.audit_log_entries
533
+ order by created_at desc
534
+ limit 100;
535
+
536
+ -- Filtrar por tipo de ação
537
+ select *
538
+ from auth.audit_log_entries
539
+ where payload->>'action' = 'login'
540
+ and created_at > now() - interval '24 hours';
541
+ ```
542
+
543
+ ### Ações registradas
544
+
545
+ | Ação | Descrição |
546
+ |------|-----------|
547
+ | `login` | Login bem-sucedido |
548
+ | `logout` | Logout |
549
+ | `signup` | Novo cadastro |
550
+ | `token_refreshed` | Refresh de access token |
551
+ | `password_recovery` | Pedido de reset de senha |
552
+ | `user_modified` | Dados do usuário atualizados |
553
+ | `user_deleted` | Conta deletada |
554
+ | `mfa_challenge_verified` | Desafio MFA verificado |
555
+ | `invite` | Usuário convidado por admin |
556
+
557
+ ### Armazenamento externo de audit logs
558
+
559
+ Por padrão, logs ficam no Postgres do projeto (tabela `auth.audit_log_entries`). Para retenção de longo prazo ou compliance (LGPD, SOC 2):
560
+
561
+ ```ts
562
+ // Edge Function — exportar audit logs para armazenamento externo
563
+ // supabase/functions/export-audit-logs/index.ts
564
+ import { createClient } from '@supabase/supabase-js'
565
+
566
+ Deno.serve(async () => {
567
+ const supabase = createClient(
568
+ Deno.env.get('SUPABASE_URL')!,
569
+ Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!
570
+ )
571
+
572
+ const since = new Date(Date.now() - 60 * 60 * 1000).toISOString() // última hora
573
+
574
+ const { data: logs } = await supabase
575
+ .from('auth.audit_log_entries')
576
+ .select('*')
577
+ .gt('created_at', since)
578
+ .order('created_at')
579
+
580
+ if (logs?.length) {
581
+ // Enviar para S3, Datadog, Elastic, etc.
582
+ await fetch(Deno.env.get('LOG_EXPORT_URL')!, {
583
+ method: 'POST',
584
+ headers: { 'Content-Type': 'application/json' },
585
+ body: JSON.stringify({ logs }),
586
+ })
587
+ }
588
+
589
+ return new Response('ok')
590
+ })
591
+ ```
592
+
593
+ ### Desabilitar armazenamento no Postgres (se usar externo)
594
+
595
+ ```toml
596
+ [auth]
597
+ # Desabilita inserção em auth.audit_log_entries (ainda envia para hooks)
598
+ enable_audit_log = false
599
+ ```
600
+
601
+ ## Regras absolutas
602
+
603
+ 1. **Produção exige SMTP custom** — o SMTP padrão do Supabase só envia para membros da equipe do projeto; sem SMTP custom, usuários não recebem emails de confirmação/reset
604
+ 2. **Habilitar CAPTCHA contra abuso de signup por bots** — signups automatizados consomem cota de email e poluem a base de usuários; Turnstile invisível tem menor atrito
605
+ 3. **Habilitar leaked password protection** — HaveIBeenPwned k-Anonymity não expõe a senha; rejeita 99%+ das senhas mais comuns em vazamentos
606
+ 4. **Site URL deve ser a URL de produção, não localhost** — usuários redirecionados para localhost perdem o fluxo de auth; verificar antes do deploy
607
+ 5. **URLs de preview precisam de entradas na allowlist** — Vercel e Netlify geram URLs dinâmicas por branch; usar wildcard específico com domínio base
608
+ 6. **Separar emails de auth dos emails de marketing** — usar subdomínio dedicado para auth; reclamações de spam do marketing não devem afetar entregabilidade transacional
609
+
610
+ ## Anti-patterns
611
+
612
+ ### Anti-pattern 1: SMTP padrão em produção
613
+
614
+ **Errado:**
615
+ ```toml
616
+ # config.toml sem configuração de SMTP
617
+ # "vai funcionar no dashboard.supabase.com" — ERRADO para usuários reais
618
+ ```
619
+
620
+ **Por quê:** o SMTP built-in do Supabase é exclusivo para desenvolvimento e testes — emails para endereços fora da equipe do projeto são silenciosamente descartados. Usuários em produção não recebem emails de confirmação ou reset de senha.
621
+
622
+ **Certo:** configurar SMTP custom (Resend, SES, Postmark) com domínio verificado, DKIM e DMARC antes de ir para produção.
623
+
624
+ ### Anti-pattern 2: Site URL apontando para localhost
625
+
626
+ **Errado:**
627
+ ```toml
628
+ [auth]
629
+ site_url = "http://localhost:3000" # copiado do .env de dev → esquecido em produção
630
+ ```
631
+
632
+ **Por quê:** após clicar no link de confirmação de email ou reset de senha, o usuário é redirecionado para `localhost:3000` — que não existe em produção. Fluxo de auth quebrado para todos os usuários.
633
+
634
+ **Certo:** `site_url` em staging/produção sempre aponta para a URL real; usar variável de ambiente ou CI/CD para garantir que o valor correto seja aplicado por ambiente.
635
+
636
+ ### Anti-pattern 3: Signup sem CAPTCHA
637
+
638
+ **Errado:**
639
+ ```ts
640
+ // Signup direto sem proteção
641
+ const { error } = await supabase.auth.signUp({ email, password })
642
+ ```
643
+
644
+ **Por quê:** sem CAPTCHA, qualquer script pode criar milhares de contas automaticamente — consumindo cota de email SMTP, poluindo a base de usuários, e potencialmente causando custos inesperados.
645
+
646
+ **Certo:** habilitar Turnstile (invisível, menos atrito) ou hCaptcha; passar `captchaToken` no `signUp()`.
647
+
648
+ ### Anti-pattern 4: Misturar emails de auth e marketing
649
+
650
+ **Errado:**
651
+ ```
652
+ Domínio: meuapp.com
653
+ Auth emails: noreply@meuapp.com (mesmo domínio/IP)
654
+ Marketing: newsletter@meuapp.com (mesmo domínio/IP)
655
+ ```
656
+
657
+ **Por quê:** alta taxa de unsubscribe ou reclamações de spam nas newsletters degrada a reputação do domínio/IP → emails de auth (confirmação, reset de senha) também caem no spam ou são bloqueados.
658
+
659
+ **Certo:**
660
+ ```
661
+ Auth: noreply@auth.meuapp.com (subdomínio dedicado, IP separado)
662
+ Marketing: news@meuapp.com (domínio principal)
663
+ ```
664
+
665
+ Reputações de email são por domínio/IP; subdominios permitem isolamento.
666
+
667
+ ## Ver também
668
+
669
+ - [supabase-auth-methods](../supabase-auth-methods/SKILL.md) — panorama de métodos de auth (email, magic link, OAuth social)
670
+ - [supabase-social-oauth](../supabase-social-oauth/SKILL.md) — OAuth social (Google, GitHub, etc.)
671
+ - [supabase-auth-hooks](../supabase-auth-hooks/SKILL.md) — hooks de autenticação (before/after events)
672
+ - [supabase-mfa](../supabase-mfa/SKILL.md) — Multi-Factor Authentication (TOTP, SMS)
673
+ - [supabase-auth-bootstrapper](../../agents/supabase-auth-bootstrapper.md) — agente que configura auth completo desde o início
674
+ - [supabase-auth-ssr](../supabase-auth-ssr/SKILL.md) — @supabase/ssr para Next.js