@luanpdd/kit-mcp 1.22.0 → 1.26.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 (33) hide show
  1. package/README.md +267 -1
  2. package/kit/agents/audit-log-implementer.md +138 -0
  3. package/kit/agents/auditor-consistencia-isolamento.md +33 -0
  4. package/kit/agents/crm-pipeline-implementer.md +89 -0
  5. package/kit/agents/debugger.md +41 -0
  6. package/kit/agents/evolution-go-integrator.md +21 -0
  7. package/kit/agents/executor.md +41 -0
  8. package/kit/agents/invite-flow-implementer.md +52 -0
  9. package/kit/agents/lgpd-compliance-auditor.md +89 -0
  10. package/kit/agents/multi-tenant-rls-writer.md +78 -0
  11. package/kit/agents/org-onboarding-implementer.md +21 -0
  12. package/kit/agents/planner.md +31 -0
  13. package/kit/agents/supabase-architect.md +17 -0
  14. package/kit/agents/supabase-auth-bootstrapper.md +80 -0
  15. package/kit/agents/supabase-column-privileges-writer.md +399 -0
  16. package/kit/agents/supabase-migration-writer.md +129 -14
  17. package/kit/agents/supabase-rbac-implementer.md +392 -0
  18. package/kit/agents/supabase-rls-hardener.md +521 -0
  19. package/kit/agents/supabase-rls-writer.md +105 -9
  20. package/kit/agents/supabase-roles-implementer.md +355 -0
  21. package/kit/agents/super-admin-implementer.md +99 -0
  22. package/kit/commands/supabase.md +55 -8
  23. package/kit/file-manifest.json +32 -24
  24. package/kit/skills/_shared-supabase/glossary.md +27 -0
  25. package/kit/skills/rbac-permissions-matrix-supabase/SKILL.md +37 -0
  26. package/kit/skills/supabase-column-level-security/SKILL.md +426 -0
  27. package/kit/skills/supabase-custom-claims-rbac/SKILL.md +472 -0
  28. package/kit/skills/supabase-database-functions/SKILL.md +85 -0
  29. package/kit/skills/supabase-migrations/SKILL.md +123 -11
  30. package/kit/skills/supabase-postgres-roles/SKILL.md +392 -0
  31. package/kit/skills/supabase-rls-defense-in-depth/SKILL.md +418 -0
  32. package/kit/skills/supabase-rls-policies/SKILL.md +462 -12
  33. package/package.json +1 -1
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: supabase-migrations
3
- description: Use ao criar arquivos de migration Supabase — naming YYYYMMDDHHmmss_short.sql, header de metadados, RLS obrigatório em toda nova tabela, granular policies.
3
+ description: Use ao criar arquivos de migration Supabase — naming YYYYMMDDHHmmss_short.sql, header de metadados, GRANT antes de ENABLE RLS, RLS obrigatório em toda nova tabela, granular policies, indices em colunas RLS. Template canônico v1.23 com 5 blocos obrigatórios para CREATE TABLE.
4
4
  ---
5
5
 
6
6
  # Supabase — Migrations
@@ -21,25 +21,112 @@ LLM carrega esta skill quando criar/editar arquivos em `supabase/migrations/`. T
21
21
  - **Header de metadados** no topo de cada migration (block comment) descrevendo Migration / Created / Purpose / Affects.
22
22
  - **lowercase em todo SQL** (alinhado com `supabase-postgres-style`).
23
23
  - **Comentários copiosos** em comandos destrutivos: `drop table`, `drop column`, `alter table ... drop column`, `truncate`, `delete from` em massa. Comentário explica o porquê + impacto.
24
+ - **`GRANT` antes de `ENABLE RLS`** (v1.23) — sempre conceda privilégios necessários aos roles `anon`/`authenticated`/`service_role` ANTES de habilitar RLS. Sem GRANT, mesmo policies "permissive" falham porque o role não tem permissão de tabela.
24
25
  - **`RLS` obrigatório em toda nova tabela** — `alter table public.<name> enable row level security;` no mesmo arquivo da criação.
25
26
  - **`granular policies`** — uma `for select`, uma `for insert`, uma `for update`, uma `for delete`. **Nunca** `for all`.
26
27
  - **`(select auth.uid())`** sempre wrapped (REGRA #1 de RLS).
28
+ - **`IS NOT NULL AND` em policies de auth** (v1.23) — `(select auth.uid()) is not null and (select auth.uid()) = user_id` para evitar silent-fail em usuários não-logados.
27
29
  - **Index nas colunas referenciadas por RLS:** `create index on public.<table> (user_id);` no mesmo arquivo.
28
30
  - Idempotência onde possível: `create table if not exists`, `create index if not exists`. Migrations rodam em ordem mas tooling pode re-executar.
29
31
  - Migrations são **append-only**. Para reverter, criar nova migration que desfaz — nunca editar migration já aplicada.
30
32
 
33
+ ## Template canônico v1.23 — CREATE TABLE com 5 blocos obrigatórios
34
+
35
+ Toda migration que cria tabela em schema exposto (`public`) deve conter os 5 blocos abaixo em ordem. Nenhum bloco é opcional. Bloco ausente = migration BLOCK pelo `supabase-rls-hardener` (v1.23).
36
+
37
+ ```sql
38
+ /*
39
+ Migration: create_<table_name>
40
+ Created: <YYYY-MM-DD>
41
+ Purpose: <one-line description>
42
+ Affects: public.<table> (new), public.<table> policies (new — 4), public.<table> index (new)
43
+ */
44
+
45
+ -- BLOCO 1: CREATE TABLE
46
+ create table if not exists public.<table> (
47
+ id uuid primary key default gen_random_uuid(),
48
+ user_id uuid not null references auth.users (id) on delete cascade,
49
+ -- ... outras colunas
50
+ created_at timestamptz not null default now(),
51
+ updated_at timestamptz not null default now()
52
+ );
53
+
54
+ -- BLOCO 2: GRANTs por role (ANTES de ENABLE RLS — v1.23)
55
+ grant select on public.<table> to anon;
56
+ grant select, insert, update, delete on public.<table> to authenticated;
57
+ grant select, insert, update, delete on public.<table> to service_role;
58
+
59
+ -- BLOCO 3: ENABLE RLS
60
+ alter table public.<table> enable row level security;
61
+
62
+ -- BLOCO 4: 4 policies granulares (uma por operação)
63
+ create policy "<table>_select_own"
64
+ on public.<table> for select to authenticated
65
+ using (
66
+ (select auth.uid()) is not null
67
+ and (select auth.uid()) = user_id
68
+ );
69
+
70
+ create policy "<table>_insert_own"
71
+ on public.<table> for insert to authenticated
72
+ with check (
73
+ (select auth.uid()) is not null
74
+ and (select auth.uid()) = user_id
75
+ );
76
+
77
+ create policy "<table>_update_own"
78
+ on public.<table> for update to authenticated
79
+ using (
80
+ (select auth.uid()) is not null
81
+ and (select auth.uid()) = user_id
82
+ )
83
+ with check (
84
+ (select auth.uid()) is not null
85
+ and (select auth.uid()) = user_id
86
+ );
87
+
88
+ create policy "<table>_delete_own"
89
+ on public.<table> for delete to authenticated
90
+ using (
91
+ (select auth.uid()) is not null
92
+ and (select auth.uid()) = user_id
93
+ );
94
+
95
+ -- BLOCO 5: Index obrigatório em colunas referenciadas pelas policies
96
+ create index if not exists <table>_user_id_idx on public.<table> (user_id);
97
+
98
+ -- BLOCO 6 (v1.24, OPCIONAL): Column-Level Privileges
99
+ -- ⚠ Adicionar APENAS se há colunas sensíveis (PII, billing, audit payload, tokens raw)
100
+ -- Para casos comuns, prefira RLS + dedicated role table (skill supabase-column-level-security)
101
+ -- Exemplo: tabela posts com coluna admin_notes visível apenas para service_role
102
+ -- revoke select on table public.<table> from authenticated;
103
+ -- grant select (id, user_id, title, content, created_at) on table public.<table> to authenticated;
104
+ -- (service_role mantém acesso total — não precisa GRANT extra)
105
+
106
+ -- BLOCO 7 (v1.26, OPCIONAL): CREATE ROLE para custom service accounts
107
+ -- ⚠ Adicionar APENAS se há service accounts internos (cron jobs, BI tools, ETL, admin scripts)
108
+ -- Para application access (end-users), prefira RLS + Custom Claims (skill supabase-custom-claims-rbac v1.25)
109
+ -- Exemplo: role dedicado para cron job de cleanup
110
+ -- create role "cron_cleanup_role" noinherit;
111
+ -- alter role "cron_cleanup_role" with bypassrls;
112
+ -- grant usage on schema public to cron_cleanup_role;
113
+ -- grant delete on public.<table> to cron_cleanup_role;
114
+ -- comment on role "cron_cleanup_role" is 'Service account para cron job de cleanup. Owner: team@company.com';
115
+ ```
116
+
31
117
  ## Patterns canônicos
32
118
 
33
- ### Criar tabela com RLS + policies granulares + index
119
+ ### Criar tabela com 5 blocos obrigatórios (v1.23) example concreto
34
120
 
35
121
  ```sql
36
122
  /*
37
123
  Migration: create_tasks
38
124
  Created: 2026-05-06
39
- Purpose: Cria tabela tasks com RLS habilitado e policies granulares por operação.
40
- Affects: public.tasks (new), public.tasks policies (new — 4 policies)
125
+ Purpose: Cria tabela tasks com GRANT + RLS habilitado + policies granulares por operação + index.
126
+ Affects: public.tasks (new), public.tasks policies (new — 4 policies), public.tasks index (new)
41
127
  */
42
128
 
129
+ -- BLOCO 1: CREATE TABLE
43
130
  create table if not exists public.tasks (
44
131
  id uuid primary key default gen_random_uuid(),
45
132
  user_id uuid not null references auth.users (id) on delete cascade,
@@ -49,28 +136,53 @@ create table if not exists public.tasks (
49
136
  updated_at timestamptz not null default now()
50
137
  );
51
138
 
139
+ -- BLOCO 2: GRANTs por role (v1.23 — antes de ENABLE RLS)
140
+ grant select on public.tasks to anon;
141
+ grant select, insert, update, delete on public.tasks to authenticated;
142
+ grant select, insert, update, delete on public.tasks to service_role;
143
+
144
+ -- BLOCO 3: ENABLE RLS
52
145
  alter table public.tasks enable row level security;
53
146
 
54
- -- granular policies: uma por operação por role
147
+ -- BLOCO 4: granular policies (uma por operação) com IS NOT NULL anti silent-fail
55
148
  create policy "users_select_own_tasks"
56
149
  on public.tasks for select to authenticated
57
- using ((select auth.uid()) = user_id);
150
+ using (
151
+ (select auth.uid()) is not null
152
+ and (select auth.uid()) = user_id
153
+ );
58
154
 
59
155
  create policy "users_insert_own_tasks"
60
156
  on public.tasks for insert to authenticated
61
- with check ((select auth.uid()) = user_id);
157
+ with check (
158
+ (select auth.uid()) is not null
159
+ and (select auth.uid()) = user_id
160
+ );
62
161
 
63
162
  create policy "users_update_own_tasks"
64
163
  on public.tasks for update to authenticated
65
- using ((select auth.uid()) = user_id)
66
- with check ((select auth.uid()) = user_id);
164
+ using (
165
+ (select auth.uid()) is not null
166
+ and (select auth.uid()) = user_id
167
+ )
168
+ with check (
169
+ (select auth.uid()) is not null
170
+ and (select auth.uid()) = user_id
171
+ );
67
172
 
68
173
  create policy "users_delete_own_tasks"
69
174
  on public.tasks for delete to authenticated
70
- using ((select auth.uid()) = user_id);
175
+ using (
176
+ (select auth.uid()) is not null
177
+ and (select auth.uid()) = user_id
178
+ );
71
179
 
72
- -- index obrigatório nas colunas usadas pela policy
180
+ -- BLOCO 5: index obrigatório nas colunas usadas pela policy
73
181
  create index if not exists tasks_user_id_idx on public.tasks (user_id);
182
+
183
+ -- BLOCO 6 (v1.24, OPCIONAL): Column-Level Privileges
184
+ -- Não aplicável neste exemplo — tasks não tem colunas sensíveis
185
+ -- Ver skill supabase-column-level-security para casos com PII / audit log / billing
74
186
  ```
75
187
 
76
188
  ### Adicionar coluna a tabela existente
@@ -0,0 +1,392 @@
1
+ ---
2
+ name: supabase-postgres-roles
3
+ description: Use ao gerenciar Postgres roles em Supabase — system access (cron jobs, BI tools, ETL, admin scripts). Distinção canônica vs RLS+Custom Claims (application access). CREATE ROLE syntax + password best practices + GRANT/REVOKE + role hierarchy (INHERIT/NOINHERIT) + 10 predefined Supabase roles. NÃO usar para "admin vs user" (use RLS + Custom Claims v1.25). v1.26 incorpora 100% da doc oficial.
4
+ ---
5
+
6
+ # Supabase — Postgres Roles
7
+
8
+ ## Quando usar (e quando NÃO usar)
9
+
10
+ Postgres roles gerenciam acesso ao banco — **system access** (service accounts internos, cron jobs, BI tools, ETL, admin scripts).
11
+
12
+ **Use Postgres roles APENAS para:**
13
+
14
+ - ✅ Service accounts internos (cron jobs com pg_cron, BI tools como Metabase, ETL scripts)
15
+ - ✅ Admin roles com BYPASSRLS (`security_admin`, `dpo_role`, `lead_manager`, `platform_admin`)
16
+ - ✅ Roles para column-level GRANTs específicos (cross-ref skill `supabase-column-level-security` v1.24)
17
+ - ✅ Custom roles que substituem service_role key em scripts (auditabilidade superior)
18
+
19
+ **NÃO use Postgres roles para:**
20
+
21
+ - ❌ "Admin vs user" application access → use **RLS + Custom Claims** (skill `supabase-custom-claims-rbac` v1.25)
22
+ - ❌ Filtrar dados por linha → use **RLS row-level** (skill `supabase-rls-policies` v1.23)
23
+ - ❌ Filtrar dados por coluna → use **Column-Level Privileges** (skill `supabase-column-level-security` v1.24)
24
+ - ❌ Substituir auth.users (auth.users é gerenciado pelo Supabase Auth — não criar roles para end-users)
25
+
26
+ Trigger phrases:
27
+
28
+ - "create role Postgres", "custom Postgres role"
29
+ - "role hierarchy", "INHERIT NOINHERIT"
30
+ - "GRANT REVOKE Postgres"
31
+ - "service account Supabase", "cron job role"
32
+ - "Postgres roles vs RLS"
33
+
34
+ ## Distinção canônica
35
+
36
+ | | Application Access | System Access |
37
+ |---|---|---|
38
+ | Mecanismo | RLS + Custom Claims | Postgres Roles |
39
+ | Quem é o "user" | End-user via JWT (`auth.uid()`) | Service account interno |
40
+ | Identidade | JWT claim (`user_role`) | Postgres role login |
41
+ | Permissions | Granular por linha/coluna | Per tabela/schema/function |
42
+ | Audit trail | RLS denial logs (42501) | pg_stat_statements por role |
43
+ | Example | "User admin pode deletar messages" | "Cron job pode SELECT em todas tabs para backup" |
44
+
45
+ ## Princípio canônico
46
+
47
+ Roles vs Users:
48
+
49
+ - **Role** = entidade Postgres que pode ter permissions
50
+ - **User** = role com `LOGIN` privilege (pode autenticar via senha)
51
+ - **Group** = role sem `LOGIN` (usado para herança de permissions)
52
+
53
+ ```sql
54
+ -- group role (sem LOGIN — usado para hierarchy)
55
+ create role "readonly_group";
56
+
57
+ -- user role (com LOGIN — service account)
58
+ create role "readonly_user" with login password 'extremely_secure_pwd';
59
+
60
+ -- user role inherita do group
61
+ grant readonly_group to readonly_user;
62
+ -- agora readonly_user tem todas permissions do readonly_group
63
+ ```
64
+
65
+ ## Pattern 1: CREATE ROLE básico
66
+
67
+ ### Group role (sem LOGIN)
68
+
69
+ ```sql
70
+ create role "billing_group";
71
+ -- usado apenas como container de permissions; não pode logar
72
+ ```
73
+
74
+ ### User role (com LOGIN PASSWORD)
75
+
76
+ ```sql
77
+ create role "billing_service" with login password 'p4ss-w0rd!sup3r_s3cur3';
78
+ ```
79
+
80
+ **Password best practices (canônico):**
81
+
82
+ 1. **12+ characters mínimo** — quanto mais longo, melhor
83
+ 2. **Use password manager** para gerar (Bitwarden, 1Password, etc.)
84
+ 3. **Mix upper + lower + numbers + special symbols** (`! @ # $ % &`)
85
+ 4. **NÃO use dictionary words** comuns
86
+ 5. **Roteie via secrets vault** — nunca hardcode em git
87
+
88
+ ### Caveat — Percent-encoding em connection string
89
+
90
+ Special symbols em password precisam ser **percent-encoded** quando usados em connection string:
91
+
92
+ ```
93
+ ANTES (raw password): p=ssword
94
+ DEPOIS (em URL): p%3Dssword
95
+
96
+ Connection string:
97
+ postgresql://postgres.projectref:p%3Dssword@aws-0-us-east-1.pooler.supabase.com:6543/postgres
98
+ ```
99
+
100
+ Tabela de encoding canônica:
101
+
102
+ | Char | Encoded |
103
+ |------|---------|
104
+ | `=` | `%3D` |
105
+ | `&` | `%26` |
106
+ | `+` | `%2B` |
107
+ | `#` | `%23` |
108
+ | `:` | `%3A` |
109
+ | `/` | `%2F` |
110
+ | `@` | `%40` |
111
+ | `space` | `%20` |
112
+
113
+ ## Pattern 2: GRANT / REVOKE permissions
114
+
115
+ GRANT canônico:
116
+
117
+ ```sql
118
+ -- permission em schema completo
119
+ grant usage on schema public to billing_service;
120
+ grant select on all tables in schema public to billing_service;
121
+
122
+ -- permission em tabela específica
123
+ grant select, insert on table public.invoices to billing_service;
124
+
125
+ -- permission em função específica
126
+ grant execute on function public.calculate_total(uuid) to billing_service;
127
+
128
+ -- permission em sequence (necessário para INSERT em tabelas com SERIAL/BIGSERIAL)
129
+ grant usage on sequence public.invoices_id_seq to billing_service;
130
+ ```
131
+
132
+ REVOKE canônico:
133
+
134
+ ```sql
135
+ revoke select on table public.invoices from billing_service;
136
+ revoke execute on function public.calculate_total(uuid) from billing_service;
137
+ ```
138
+
139
+ **Caveat — Default privileges para novos objetos:**
140
+
141
+ GRANT em "all tables" só cobre tabelas **existentes**. Para tabelas futuras criadas no schema, use `ALTER DEFAULT PRIVILEGES`:
142
+
143
+ ```sql
144
+ -- todas tabelas futuras criadas em public terão SELECT GRANT para billing_service
145
+ alter default privileges in schema public
146
+ grant select on tables to billing_service;
147
+ ```
148
+
149
+ ## Pattern 3: Role Hierarchy (INHERIT / NOINHERIT)
150
+
151
+ INHERIT (default): child role herda permissions do parent.
152
+
153
+ ```sql
154
+ -- group com permissions base
155
+ create role "readers";
156
+ grant select on all tables in schema public to readers;
157
+
158
+ -- user inherita
159
+ create role "alice" with login password 'pwd1';
160
+ grant readers to alice;
161
+ -- alice agora tem SELECT em todas tabelas public (via readers)
162
+
163
+ -- multi-level hierarchy
164
+ create role "admins";
165
+ grant readers to admins; -- admins inherita de readers
166
+ grant insert, update, delete on all tables in schema public to admins;
167
+
168
+ create role "bob" with login password 'pwd2';
169
+ grant admins to bob;
170
+ -- bob inherita de admins (que inherita de readers) — full CRUD em public
171
+ ```
172
+
173
+ NOINHERIT: child role tem que **explicitamente** assumir parent role para usar permissions.
174
+
175
+ ```sql
176
+ create role "superuser_proxy" noinherit;
177
+ grant postgres to superuser_proxy;
178
+
179
+ -- Para usar permissions de postgres, superuser_proxy precisa SET ROLE:
180
+ set role postgres;
181
+ -- agora opera como postgres
182
+ reset role;
183
+ ```
184
+
185
+ **Quando usar NOINHERIT:**
186
+
187
+ - Roles superuser (postgres) — exigir SET ROLE explícito como guard
188
+ - Audit trail mais claro (queries mostram a role ativa)
189
+ - Princípio canônico: opt-in explícito em vez de implícito
190
+
191
+ ## 10 Predefined Supabase Roles (documentação)
192
+
193
+ Supabase configura 10 roles automaticamente em todo projeto. **Não criar substitutos** — documentar e usar conforme apropriado.
194
+
195
+ ### `postgres`
196
+ **Tipo:** Admin/superuser. **Quando usar:** scripts de admin via dashboard ou psql direto.
197
+ **NUNCA:** dar password ao third-party ou expor.
198
+
199
+ ### `anon`
200
+ **Tipo:** Public unauthenticated. **Quando usar:** requests sem JWT (cliente deslogado).
201
+ **Caveat:** `anon` Postgres role ≠ anonymous Auth user (cross-ref skill `supabase-rls-policies` v1.23).
202
+
203
+ ### `authenticator`
204
+ **Tipo:** PostgREST switch role. **Quando usar:** internal — PostgREST recebe JWT, valida, e switches para `anon` ou `authenticated` baseado em claims.
205
+ **Caveat:** acesso muito limitado — apenas SWITCH ROLE.
206
+
207
+ ### `authenticated`
208
+ **Tipo:** Logged-in users. **Quando usar:** requests com JWT válido (autenticado).
209
+
210
+ ### `service_role`
211
+ **Tipo:** Bypass RLS. **Quando usar:** backend tasks (Edge Functions, scripts admin).
212
+ **NUNCA:** expor ao cliente — vazamento = acesso total ao DB.
213
+
214
+ ### `supabase_auth_admin`
215
+ **Tipo:** Auth middleware. **Quando usar:** internal — Supabase Auth service.
216
+ **Caveat:** GRANT EXECUTE em Custom Access Token Auth Hook (cross-ref skill `supabase-custom-claims-rbac` v1.25); scope `auth` schema.
217
+
218
+ ### `supabase_storage_admin`
219
+ **Tipo:** Storage middleware. **Quando usar:** internal — Supabase Storage service. Scope `storage` schema.
220
+
221
+ ### `supabase_etl_admin`
222
+ **Tipo:** Replication. **Quando usar:** internal — Replication powered by Supabase ETL. Read-all + bypass RLS + write `etl` schema.
223
+
224
+ ### `dashboard_user`
225
+ **Tipo:** Supabase UI. **Quando usar:** internal — commands via Supabase dashboard.
226
+
227
+ ### `supabase_admin`
228
+ **Tipo:** Internal admin. **Quando usar:** internal — upgrades + automations.
229
+
230
+ ## Pattern 4: Custom service account roles
231
+
232
+ Caso canônico — criar role dedicado em vez de service_role API key:
233
+
234
+ ```sql
235
+ -- 1. role para cron job (sem LOGIN — usado via pg_cron)
236
+ create role "cron_job_role" noinherit;
237
+ -- bypass RLS para acessar todas orgs
238
+ alter role "cron_job_role" with bypassrls;
239
+
240
+ -- 2. GRANTs específicos
241
+ grant usage on schema public to cron_job_role;
242
+ grant select, insert, delete on table public.audit_log to cron_job_role;
243
+
244
+ -- 3. pg_cron usa este role
245
+ select cron.schedule(
246
+ 'cleanup_old_logs',
247
+ '0 3 * * *',
248
+ $$ delete from public.audit_log where created_at < now() - interval '90 days' $$
249
+ );
250
+ -- pg_cron executa as queries com este role; auditabilidade superior vs service_role API key
251
+ ```
252
+
253
+ ```sql
254
+ -- role para BI tool (Metabase) — read-only com login
255
+ create role "metabase_reader" with login password 'percent-encode-this!';
256
+ alter role "metabase_reader" with bypassrls; -- BI precisa ver todas linhas
257
+
258
+ grant usage on schema public to metabase_reader;
259
+ grant select on all tables in schema public to metabase_reader;
260
+ alter default privileges in schema public
261
+ grant select on tables to metabase_reader;
262
+ ```
263
+
264
+ ## Changing postgres password
265
+
266
+ Mudar password do `postgres` role:
267
+
268
+ 1. **Dashboard:** Database Settings page → "Database password" → enter new
269
+ 2. **Sem downtime:** serviços internos (PostgREST, PgBouncer, etc.) auto-update
270
+ 3. **External services com hardcoded credentials:** manual update necessário (revisar deploy configs)
271
+
272
+ **NÃO:** dar password do `postgres` role para third-party — crie role dedicado.
273
+
274
+ ## Auditoria — pg_stat_statements por role
275
+
276
+ Cada role tem queries rastreáveis em `pg_stat_statements`:
277
+
278
+ ```sql
279
+ select
280
+ rolname,
281
+ count(*) as query_count,
282
+ sum(total_exec_time)::numeric(10,2) as total_time_ms
283
+ from pg_stat_statements s
284
+ join pg_roles r on s.userid = r.oid
285
+ where rolname not in ('postgres', 'authenticator') -- filtrar admin
286
+ group by rolname
287
+ order by total_time_ms desc;
288
+ ```
289
+
290
+ Identificar qual service account está consumindo mais — útil para debug + capacity planning.
291
+
292
+ ## Anti-patterns
293
+
294
+ ### Anti-pattern 1: Usar service_role API key para tudo
295
+
296
+ **Errado:**
297
+ ```bash
298
+ # .env do cron job
299
+ SUPABASE_KEY=eyJ...service_role_key...
300
+ ```
301
+
302
+ **Por quê:** sem auditabilidade — todas queries logam como `service_role`; difícil identificar qual script fez o quê.
303
+
304
+ **Certo:** criar role dedicado por service account:
305
+ ```sql
306
+ create role "cron_billing_role" noinherit;
307
+ alter role "cron_billing_role" with bypassrls;
308
+ -- GRANTs específicos
309
+ -- pg_cron usa este role; queries logam com identidade clara
310
+ ```
311
+
312
+ ### Anti-pattern 2: Custom role para "admin vs user" application access
313
+
314
+ **Errado:**
315
+ ```sql
316
+ -- criar role "admin" Postgres para gerenciar quem é admin no app
317
+ create role "app_admin";
318
+ -- ... add users to this role ...
319
+ ```
320
+
321
+ **Por quê:** Postgres roles não são designed para application access — não dinâmico, não auditável, mistura system + application concerns.
322
+
323
+ **Certo:** use RLS + Custom Claims (skill `supabase-custom-claims-rbac` v1.25) — `user_role: 'admin'` no JWT via auth hook, consultado por `authorize()`.
324
+
325
+ ### Anti-pattern 3: Password sem percent-encoding em URL
326
+
327
+ **Errado:**
328
+ ```
329
+ postgresql://user:p=ssword@host/db
330
+ ```
331
+
332
+ **Por quê:** `=` é parseado como query string separator — conexão falha.
333
+
334
+ **Certo:**
335
+ ```
336
+ postgresql://user:p%3Dssword@host/db
337
+ ```
338
+
339
+ ### Anti-pattern 4: INHERIT em superuser-like role
340
+
341
+ **Errado:**
342
+ ```sql
343
+ create role "dba_role" inherit; -- inherit default em todos roles
344
+ grant postgres to dba_role;
345
+ -- dba_role agora tem postgres privileges implicitly
346
+ ```
347
+
348
+ **Por quê:** sem audit trail explícito de quando privileges admin são usados.
349
+
350
+ **Certo:** NOINHERIT + SET ROLE explícito:
351
+ ```sql
352
+ create role "dba_role" noinherit;
353
+ grant postgres to dba_role;
354
+ -- usuário precisa: set role postgres; ...; reset role;
355
+ -- queries logam com identidade postgres durante operação
356
+ ```
357
+
358
+ ### Anti-pattern 5: Criar role sem documentação
359
+
360
+ **Errado:**
361
+ ```sql
362
+ create role "xyz" with login password 'pwd';
363
+ -- 6 meses depois, ninguém sabe pra que serve
364
+ ```
365
+
366
+ **Por quê:** sem documentação, próximo dev assume é abandoned + remove ou mantém indefinidamente.
367
+
368
+ **Certo:** sempre comment no migration + entry em README:
369
+ ```sql
370
+ -- role para Metabase BI conectar em produção (read-only)
371
+ -- Owner: data-team@company.com
372
+ -- Created: 2026-05-11 v1.26
373
+ create role "metabase_reader" with login password '<from-vault>';
374
+ comment on role "metabase_reader" is 'BI tool service account — read-only. Owner: data-team@company.com';
375
+ ```
376
+
377
+ ## Cross-suite integration (v1.26)
378
+
379
+ Esta skill é base para agent novo `supabase-roles-implementer` (Phase 145) — recebe spec via `Task()` e materializa CREATE ROLE + GRANT/REVOKE + hierarchy. Pattern de handoff cooperativo herdado de v1.23-v1.25.
380
+
381
+ Para column-level GRANTs específicos por role, **combine** com skill `supabase-column-level-security` (v1.24). Para custom claims que entregam `user_role` no JWT, use skill `supabase-custom-claims-rbac` (v1.25) — Postgres roles são para system access; custom claims são para application access.
382
+
383
+ ## Ver também
384
+
385
+ - [supabase-roles-implementer](../../agents/supabase-roles-implementer.md) (v1.26) — canonical materializer
386
+ - [supabase-rls-policies](../supabase-rls-policies/SKILL.md) (v1.23) — section "Postgres Roles vs RLS — quando usar qual" (v1.26)
387
+ - [supabase-rls-defense-in-depth](../supabase-rls-defense-in-depth/SKILL.md) (v1.23) — Camada 10 (Postgres Roles Hierarchy) v1.26
388
+ - [supabase-database-functions](../supabase-database-functions/SKILL.md) — GRANT EXECUTE patterns
389
+ - [supabase-column-level-security](../supabase-column-level-security/SKILL.md) (v1.24) — combinar com column-level GRANTs por role
390
+ - [supabase-custom-claims-rbac](../supabase-custom-claims-rbac/SKILL.md) (v1.25) — distinção canônica system access vs application access
391
+ - [glossário compartilhado](../_shared-supabase/glossary.md) — termos Postgres roles, INHERIT/NOINHERIT, LOGIN PASSWORD, GRANT/REVOKE syntax, role hierarchy, predefined Supabase roles, role switching authenticator, percent-encoding password
392
+ - Doc oficial Postgres: [Database Roles](https://www.postgresql.org/docs/current/database-roles.html), [Role Membership](https://www.postgresql.org/docs/current/role-membership.html), [Function Permissions](https://www.postgresql.org/docs/current/perm-functions.html)