@luanpdd/kit-mcp 1.19.0 → 1.21.0

package/kit/skills/multi-tenant-rls-hierarchy/SKILL.md

@@ -0,0 +1,338 @@
+---
+name: multi-tenant-rls-hierarchy
+description: Use ao escrever RLS hierárquica multi-tenant (org→dept→role→permission→super-admin bypass) em Supabase. 4 helper functions PG canônicas em schema private (STABLE), policies compostas com PERMISSIVE para super_admin, herança dept→org via coalesce.
+---
+
+# Multi-Tenant RLS Hierarchy — Helper Functions + Policies
+
+## Quando usar
+
+LLM carrega esta skill ao escrever RLS para tabelas em app B2B multi-tenant com hierarquia firm→department→leader→collaborator. Trigger phrases:
+
+- "RLS multi-tenant hierárquica", "RLS org dept role"
+- "helper function private", "is_member_of", "has_role", "has_permission", "is_super_admin"
+- "policy composta com super_admin bypass"
+- "department member herda role"
+- "PERMISSIVE policy super admin"
+
+Esta skill **estende** [`supabase-rls-policies`](../supabase-rls-policies/SKILL.md) (v1.8) — herda anti-pitfalls básicos (`(select auth.uid())` wrapper, no `user_metadata`, granular policies, indexes) e adiciona hierarquia + super_admin bypass.
+
+## Regras absolutas
+
+**REGRA #1 (helper functions em schema `private`):** Funções PG de RLS **DEVEM** estar em schema `private` — NÃO em `public`. PostgREST não expõe schema `private` automaticamente, então funções não viram endpoints REST acidentalmente.
+
+**REGRA #2 (STABLE marker obrigatório):** Helper functions usadas em policy **DEVEM** ser marcadas `STABLE` (não default `VOLATILE`). VOLATILE re-executa por linha — degradação de até 1000× em tabelas grandes.
+
+**REGRA #3 (security invoker + search_path = ''):** Helper functions **DEVEM** ter `security invoker` (default seguro) + `set search_path = ''` (previne search path injection).
+
+**REGRA #4 (super_admin via PERMISSIVE separada):** Bypass de super_admin **NÃO** é OR dentro da policy normal. É uma policy `as permissive` separada. PostgreSQL combina policies PERMISSIVE com OR — admin policy concedendo acesso = bypass total preservando granularidade.
+
+**REGRA #5 (herança dept→org via coalesce):** `department_members.role_id` NULL = herda do `organization_members.role_id` da mesma `(org, user)`. Resolução via função `private.effective_role_in_dept(p_dept_id, p_user_id)` que retorna `coalesce(dm.role_id, om.role_id)`.
+
+**REGRA #6 (todas anti-pitfalls v1.8 herdadas):** Aplicam-se SEMPRE — `(select auth.uid())` wrapper, NUNCA `user_metadata` em authz, 4 policies granulares (não `for all`), `to authenticated`/`to anon` explícito, indexes nas colunas das policies. Ver [`supabase-rls-policies`](../supabase-rls-policies/SKILL.md).
+
+## Patterns canônicos
+
+### 4 helper functions canônicas — DDL completo
+
+```sql
+-- Schema private (não exposto via PostgREST)
+create schema if not exists private;
+
+-- 1. is_member_of — checa se user é member ativo de uma org
+create or replace function private.is_member_of(p_org_id uuid)
+returns boolean
+language sql
+stable                        -- REGRA #2 — re-execução cacheada
+security invoker              -- REGRA #3 — usa permissões do caller
+set search_path = ''          -- REGRA #3 — previne injection
+as $$
+  select exists (
+    select 1 from public.organization_members
+    where org_id = p_org_id
+      and user_id = (select auth.uid())
+      and status = 'active'
+  );
+$$;
+
+-- 2. has_role — checa se user tem role específica numa org
+create or replace function private.has_role(p_org_id uuid, p_role_name text)
+returns boolean
+language sql
+stable
+security invoker
+set search_path = ''
+as $$
+  select exists (
+    select 1 from public.organization_members om
+    join public.roles r on r.id = om.role_id
+    where om.org_id = p_org_id
+      and om.user_id = (select auth.uid())
+      and om.status = 'active'
+      and r.name = p_role_name
+  );
+$$;
+
+-- 3. has_permission — checa se user tem permission resource:action numa org
+create or replace function private.has_permission(p_action text, p_resource text, p_org_id uuid)
+returns boolean
+language sql
+stable
+security invoker
+set search_path = ''
+as $$
+  select exists (
+    select 1
+    from public.organization_members om
+    join public.role_permissions rp on rp.role_id = om.role_id
+    join public.permissions p on p.id = rp.permission_id
+    where om.org_id = p_org_id
+      and om.user_id = (select auth.uid())
+      and om.status = 'active'
+      and p.action = p_action
+      and p.resource = p_resource
+  );
+$$;
+
+-- 4. is_super_admin — checa flag em JWT app_metadata
+create or replace function private.is_super_admin()
+returns boolean
+language sql
+stable
+security invoker
+set search_path = ''
+as $$
+  select coalesce(
+    ((select auth.jwt())->'app_metadata'->>'super_admin')::boolean,
+    false
+  );
+$$;
+```
+
+**Indexes obrigatórios** (de [`multi-tenant-performance-scaling`](../multi-tenant-performance-scaling/SKILL.md)):
+
+```sql
+-- Partial index — REGRA #3 da skill performance
+create index if not exists organization_members_user_org_active_idx
+  on public.organization_members (user_id, org_id)
+  where status = 'active';
+
+create index if not exists role_permissions_role_idx
+  on public.role_permissions (role_id);
+
+create index if not exists permissions_action_resource_idx
+  on public.permissions (action, resource);
+```
+
+### Policy hierárquica composta — exemplo `leads`
+
+```sql
+-- Tabela leads multi-tenant
+create table public.leads (
+  id uuid primary key default gen_random_uuid(),
+  org_id uuid not null references public.organizations(id) on delete cascade,
+  dept_id uuid references public.departments(id) on delete set null,
+  contact_name text not null,
+  contact_email text,
+  contact_phone text,
+  stage text not null default 'lead' check (stage in ('lead','qualified','proposal','negotiation','won','lost')),
+  owner_id uuid references auth.users(id) on delete set null,
+  created_at timestamptz not null default now(),
+  unique (org_id, contact_email),
+  unique (org_id, contact_phone)
+);
+
+alter table public.leads enable row level security;
+
+-- POLICY 1: SELECT — member da org pode ler todos leads da org
+create policy "leads_select_member"
+  on public.leads
+  for select
+  to authenticated
+  using (private.is_member_of(org_id));
+
+-- POLICY 2: INSERT — member com permission leads:create
+create policy "leads_insert_with_permission"
+  on public.leads
+  for insert
+  to authenticated
+  with check (
+    private.has_permission('create', 'leads', org_id)
+  );
+
+-- POLICY 3: UPDATE — member com permission leads:update OU é owner do lead
+create policy "leads_update_with_permission_or_owner"
+  on public.leads
+  for update
+  to authenticated
+  using (
+    private.has_permission('update', 'leads', org_id)
+    or owner_id = (select auth.uid())
+  )
+  with check (
+    private.has_permission('update', 'leads', org_id)
+    or owner_id = (select auth.uid())
+  );
+
+-- POLICY 4: DELETE — apenas admin/owner role
+create policy "leads_delete_admin_owner"
+  on public.leads
+  for delete
+  to authenticated
+  using (
+    private.has_role(org_id, 'admin') or private.has_role(org_id, 'owner')
+  );
+
+-- POLICY 5 (PERMISSIVE — REGRA #4): super_admin bypass para todas operações
+create policy "leads_super_admin_bypass"
+  on public.leads
+  as permissive   -- combinação OR com policies normais
+  for all          -- super_admin pode tudo
+  to authenticated
+  using (private.is_super_admin())
+  with check (private.is_super_admin());
+
+-- Index obrigatório nas colunas filtradas
+create index leads_org_dept_idx on public.leads (org_id, dept_id);
+create index leads_owner_idx on public.leads (owner_id) where owner_id is not null;
+```
+
+### Herança dept→org — função `effective_role_in_dept`
+
+```sql
+-- 5. effective_role_in_dept — retorna role do user no contexto do dept
+-- (NULL em department_members.role_id = herda do organization_members)
+create or replace function private.effective_role_in_dept(p_dept_id uuid, p_user_id uuid)
+returns uuid
+language sql
+stable
+security invoker
+set search_path = ''
+as $$
+  select coalesce(dm.role_id, om.role_id)
+  from public.departments d
+  join public.organization_members om on om.org_id = d.org_id and om.user_id = p_user_id
+  left join public.department_members dm on dm.dept_id = p_dept_id and dm.user_id = p_user_id
+  where d.id = p_dept_id;
+$$;
+
+-- Helper: has_role no contexto de um dept (resolve herança)
+create or replace function private.has_role_in_dept(p_dept_id uuid, p_role_name text)
+returns boolean
+language sql
+stable
+security invoker
+set search_path = ''
+as $$
+  select exists (
+    select 1 from public.roles r
+    where r.id = private.effective_role_in_dept(p_dept_id, (select auth.uid()))
+      and r.name = p_role_name
+  );
+$$;
+```
+
+### Validar isolation via query — useful em testing
+
+```sql
+-- Listar tabelas com `org_id` mas SEM RLS habilitada (red flag)
+select c.relname
+from pg_class c
+join pg_attribute a on a.attrelid = c.oid
+where a.attname = 'org_id'
+  and c.relkind = 'r'
+  and c.relrowsecurity = false;
+
+-- Listar policies que referenciam helper functions canônicas
+select policyname, tablename, qual
+from pg_policies
+where qual like '%private.is_member_of%'
+   or qual like '%private.has_permission%'
+   or qual like '%private.is_super_admin%';
+```
+
+## Anti-patterns
+
+### Anti-pattern 1: Helper functions em `public` (expostos via PostgREST)
+
+**Errado:**
+```sql
+create function public.is_member_of(p_org_id uuid) returns boolean ...
+```
+
+**Por quê:** PostgREST expõe automaticamente `/rpc/is_member_of?p_org_id=...`. Endpoint vira público acessível, atacante pode probe quem é member de qual org.
+
+**Certo:** schema `private` (PostgREST ignora por default).
+
+### Anti-pattern 2: super_admin bypass via OR na policy normal
+
+**Errado:**
+```sql
+create policy "leads_select" on public.leads
+  for select
+  to authenticated
+  using (
+    private.is_member_of(org_id)
+    or private.is_super_admin()  -- bypass embutido
+  );
+```
+
+**Por quê:** funciona mas mistura semânticas. Mais difícil de auditar (qual é a "policy normal" vs "bypass"?). Mistura severidade — quando você desativar super_admin para teste, precisa editar todas as policies.
+
+**Certo:** policy `as permissive` separada para super_admin (REGRA #4). PostgreSQL faz OR entre policies PERMISSIVE.
+
+### Anti-pattern 3: Helper function VOLATILE (default)
+
+**Errado:**
+```sql
+create function private.is_member_of(p_org_id uuid)
+returns boolean
+language sql
+-- sem STABLE — default VOLATILE
+as $$ ... $$;
+```
+
+**Por quê:** ver [`multi-tenant-performance-scaling`](../multi-tenant-performance-scaling/SKILL.md) Anti-pattern 1. Re-execução por linha = degradação 200×.
+
+**Certo:** marcar `STABLE` (REGRA #2).
+
+### Anti-pattern 4: department_members sem coalesce — herança quebrada
+
+**Errado:**
+```sql
+-- Policy lê role direto de department_members, ignorando NULL
+using (
+  exists (
+    select 1 from public.department_members dm
+    join public.roles r on r.id = dm.role_id
+    where dm.user_id = (select auth.uid()) and r.name = 'admin'
+  )
+)
+```
+
+**Por quê:** se `dm.role_id IS NULL`, JOIN não casa, role efetiva não é resolvida → user adicionado ao dept sem role explícita não tem permissão (deveria herdar do org_members).
+
+**Certo:** usar `private.effective_role_in_dept` que faz coalesce.
+
+### Anti-pattern 5: super_admin sem audit log
+
+**Errado:**
+```sql
+-- super_admin policy permite ler/modificar tudo sem registrar quem foi
+create policy "super_admin_bypass" on public.leads as permissive for all to authenticated using (private.is_super_admin()) with check (private.is_super_admin());
+-- Mas... onde está o audit?
+```
+
+**Por quê:** super_admin sem audit = ninguém consegue investigar incident "quem deletou todos os leads da org X em 03/04?". Compliance LGPD exige audit de acesso a dados.
+
+**Certo:** policy super_admin OK, mas **toda operação super_admin** deve emitir evento `super_admin_action` em `audit_log` (Phase 109). Trigger AFTER INSERT/UPDATE/DELETE em tabelas críticas que checa `private.is_super_admin()` e registra.
+
+## Ver também
+
+- [supabase-rls-policies](../supabase-rls-policies/SKILL.md) — anti-patterns base v1.8 herdados (REGRA #6)
+- [b2b-saas-architecture](../b2b-saas-architecture/SKILL.md) — schema canônico que esta skill cobre com RLS
+- [multi-tenant-performance-scaling](../multi-tenant-performance-scaling/SKILL.md) — STABLE marker + partial indexes (REGRA #2)
+- [rbac-permissions-matrix-supabase](../rbac-permissions-matrix-supabase/SKILL.md) — modelagem permissions consumed por `private.has_permission`
+- [super-admin-platform-pattern](../super-admin-platform-pattern/SKILL.md) — Phase 111, super_admin operations
+- [audit-log-multi-tenant](../audit-log-multi-tenant/SKILL.md) — Phase 109, audit `super_admin_action` (Anti-pattern 5)
+- [_shared-multi-tenant/glossary.md](../_shared-multi-tenant/glossary.md) — termos `RBAC`, `permission matrix`, `role escalation rule`

package/kit/skills/org-onboarding-flow/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: org-onboarding-flow
+description: Use ao implementar fluxo signup → criar org → primeiro admin → setup wizard em B2B SaaS Supabase. Atomicidade na criação (org + first member em 1 trx). Slug imutável + redirect trail. Setup wizard separado (não bloqueia signup).
+---
+
+# Org Onboarding Flow — B2B SaaS Multi-Tenant
+
+## Quando usar
+
+LLM carrega esta skill ao implementar onboarding de novo tenant em B2B SaaS Supabase. Trigger phrases:
+
+- "org onboarding", "criar organização", "primeiro admin"
+- "setup wizard", "tenant signup", "first user becomes admin"
+- "create org transaction", "organization creation atomic"
+- "owner role assignment", "org slug strategy"
+
+Esta skill é consumida pelo agent `org-onboarding-implementer` (Phase 107) que materializa migration + Edge Function.
+
+## Regras absolutas
+
+**REGRA #1 (atomicidade):** Criação de `organizations` row + insert em `organization_members` (com role 'owner') **DEVEM** estar na **mesma transação SQL**. Janela entre criar org e adicionar membership = race condition (request paralelo pode ver org sem owner = inconsistente).
+
+**REGRA #2 (primeiro admin = creator):** Usuário que criou a org ganha `role = 'owner'` automaticamente. Sem invite, sem aprovação. Se org tem `owner_id` field, ele = `auth.uid()`.
+
+**REGRA #3 (slug imutável após criação):** Mutação requer `organization_slug_history` entry + redirect 301 (ver skill [`b2b-saas-architecture`](../b2b-saas-architecture/SKILL.md) REGRA #3).
+
+**REGRA #4 (setup wizard async):** Setup wizard (logo, branding, member invites iniciais) **NÃO bloqueia** signup. User pode usar org imediatamente após criação. Wizard é "complete in background" pattern.
+
+**REGRA #5 (slug uniqueness):** Constraint UNIQUE em `organizations.slug` + check `slug ~ '^[a-z0-9-]+$'` + length 2-60. Reservar slugs sistêmicos (`api`, `admin`, `app`, `www`, `dashboard`, `support`, `help`).
+
+## Patterns canônicos
+
+### SQL — criação atômica (RPC function)
+
+```sql
+-- RPC chamada pelo frontend após signup
+create or replace function public.create_organization(
+  p_name text,
+  p_slug text
+)
+returns uuid
+language plpgsql
+security invoker  -- usa permissions do user autenticado
+set search_path = ''
+as $$
+declare
+  new_org_id uuid;
+  owner_role_id uuid;
+begin
+  -- 1. validar slug não está reservado
+  if p_slug = any (array['api', 'admin', 'app', 'www', 'dashboard', 'support', 'help', 'docs', 'blog', 'auth']) then
+    raise exception 'slug % is reserved', p_slug;
+  end if;
+
+  -- 2. criar organization
+  insert into public.organizations (name, slug, owner_id, plan, status)
+  values (p_name, p_slug, (select auth.uid()), 'free', 'active')
+  returning id into new_org_id;
+
+  -- 3. criar role 'owner' built-in para esta org
+  insert into public.roles (org_id, name, description, is_built_in)
+  values (new_org_id, 'owner', 'Owner — full control of organization', true)
+  returning id into owner_role_id;
+
+  -- 4. criar role 'admin' built-in
+  insert into public.roles (org_id, name, description, is_built_in)
+  values (new_org_id, 'admin', 'Admin — manage members and settings', true);
+
+  -- 5. criar role 'member' built-in
+  insert into public.roles (org_id, name, description, is_built_in)
+  values (new_org_id, 'member', 'Member — standard access', true);
+
+  -- 6. criar membership do creator como owner
+  insert into public.organization_members (org_id, user_id, role_id, status)
+  values (new_org_id, (select auth.uid()), owner_role_id, 'active');
+
+  return new_org_id;
+end;
+$$;
+
+-- Permitir que authenticated chame esta RPC
+grant execute on function public.create_organization(text, text) to authenticated;
+```
+
+**Uso no client (TypeScript + @supabase/ssr):**
+```typescript
+const { data: orgId, error } = await supabase
+  .rpc('create_organization', { p_name: 'Acme Corp', p_slug: 'acme' })
+
+if (error) throw error
+// Redirect para /orgs/acme/dashboard
+```
+
+### Edge Function — setup wizard async
+
+```typescript
+// supabase/functions/org-setup-wizard/index.ts
+// PT-BR: Edge Function para inicializar dados default da org após criação
+// (categorias, templates, sample data, etc.) — NÃO bloqueia signup
+import { createClient } from 'jsr:@supabase/supabase-js@2'
+
+Deno.serve(async (req) => {
+  const auth = req.headers.get('Authorization')
+  if (!auth) return new Response('unauthorized', { status: 401 })
+
+  const supabase = createClient(
+    Deno.env.get('SUPABASE_URL')!,
+    Deno.env.get('SUPABASE_ANON_KEY')!,  // anon — preserva RLS
+    { global: { headers: { Authorization: auth } } }
+  )
+
+  const { org_id } = await req.json()
+
+  // Validar que user é owner da org via RLS
+  const { data: membership } = await supabase
+    .from('organization_members')
+    .select('id, roles(name)')
+    .eq('org_id', org_id)
+    .eq('user_id', (await supabase.auth.getUser()).data.user!.id)
+    .single()
+
+  if (!membership || (membership.roles as any).name !== 'owner') {
+    return new Response('only owner can run setup wizard', { status: 403 })
+  }
+
+  // Inicializar dados default (categorias, etc.)
+  await supabase.from('default_categories').insert([...])
+
+  return new Response(JSON.stringify({ ok: true }), {
+    headers: { 'Content-Type': 'application/json' }
+  })
+})
+```
+
+### State machine — signup → org → admin → ready
+
+```
+signup_completed
+    ↓
+RPC create_organization (atomic)
+    ↓
+org_created + first_admin_created  (mesma transação)
+    ↓
+[redirect /orgs/<slug>/dashboard]    ← user já pode usar
+    ↓
+[background: setup_wizard Edge Function]
+    ↓
+wizard_completed
+```
+
+User vê o dashboard imediatamente. Wizard roda em background fire-and-forget (`EdgeRuntime.waitUntil` ou client-side promise sem await).
+
+### Slug history — suporte a redirect 301
+
+```sql
+-- Trigger registra mudança de slug (ver b2b-saas-architecture)
+-- App side (Next.js middleware):
+
+import { NextRequest, NextResponse } from 'next/server'
+import { createClient } from '@/lib/supabase/server'
+
+export async function middleware(req: NextRequest) {
+  const slug = req.nextUrl.pathname.split('/')[2] // /orgs/[slug]/...
+
+  if (!slug) return NextResponse.next()
+
+  const supabase = await createClient()
+  const { data: org } = await supabase
+    .from('organizations')
+    .select('slug')
+    .eq('slug', slug)
+    .maybeSingle()
+
+  if (org) return NextResponse.next() // slug atual existe
+
+  // Procurar em slug_history (slug antigo)
+  const { data: oldSlug } = await supabase
+    .from('organization_slug_history')
+    .select('new_slug')
+    .eq('old_slug', slug)
+    .order('changed_at', { ascending: false })
+    .maybeSingle()
+
+  if (oldSlug) {
+    const newPath = req.nextUrl.pathname.replace(`/orgs/${slug}/`, `/orgs/${oldSlug.new_slug}/`)
+    return NextResponse.redirect(new URL(newPath, req.url), 301)
+  }
+
+  return NextResponse.next() // 404 será servido pela page
+}
+
+export const config = {
+  matcher: '/orgs/:slug/:path*'
+}
+```
+
+## Anti-patterns
+
+### Anti-pattern 1: Criar org sem owner (race window)
+
+**Errado:**
+```typescript
+// 2 requests separados — janela de race
+const { data: org } = await supabase.from('organizations').insert({ ... }).select().single()
+await supabase.from('organization_members').insert({ org_id: org.id, user_id: ..., role_id: ... })
+```
+
+**Por quê:** entre os 2 requests, query paralela pode ler org sem owner (`select * from organizations` retorna a row, mas `organization_members` ainda não tem). Trigger ou outra Edge Function pode disparar e ver inconsistência.
+
+**Certo:** RPC `create_organization` faz ambos em transação SQL única.
+
+### Anti-pattern 2: Setup wizard bloqueia signup
+
+**Errado:**
+```typescript
+// User espera 30s+ para wizard completar antes de ver dashboard
+const { data: org } = await supabase.rpc('create_organization', { ... })
+await supabase.functions.invoke('org-setup-wizard', { body: { org_id: org.id } }) // BLOCKING!
+router.push(`/orgs/${slug}/dashboard`)
+```
+
+**Por quê:** UX terrível — first impression é "app é lento". Conversion cai (study Stripe: cada 1s atraso = 7% drop em signup completion).
+
+**Certo:** dashboard renderiza imediatamente; wizard roda em background com indicador subtle ("preparando seu workspace..." que some quando termina).
+
+### Anti-pattern 3: Slug pode mudar sem trail
+
+**Errado:**
+```sql
+update organizations set slug = 'new-acme' where id = '...';
+-- Sem entry em organization_slug_history
+```
+
+**Por quê:** ver Anti-pattern 2 em [`b2b-saas-architecture`](../b2b-saas-architecture/SKILL.md). Bookmarks/webhooks/OAuth callbacks quebram silenciosamente.
+
+**Certo:** trigger `track_org_slug_change` automático + middleware redirect 301.
+
+### Anti-pattern 4: Slugs sistêmicos não-reservados
+
+**Errado:**
+```sql
+-- User cria org com slug = 'admin' → URL /orgs/admin/dashboard conflita com /admin/* da plataforma
+```
+
+**Por quê:** roteamento ambíguo, conflito com Vercel preview deployments (`*-vercel.app`), conflito com cookies/CORS.
+
+**Certo:** allowlist em RPC `create_organization` ou check constraint na coluna `slug`.
+
+## Ver também
+
+- [b2b-saas-architecture](../b2b-saas-architecture/SKILL.md) — schema canônico de `organizations`, `organization_members`, `organization_slug_history`
+- [member-invite-flow](../member-invite-flow/SKILL.md) — Phase 110, fluxo de invite após onboarding
+- [super-admin-platform-pattern](../super-admin-platform-pattern/SKILL.md) — Phase 111, super-admin pode criar orgs em nome de outros (impersonation)
+- [supabase-migration-writer](../../agents/supabase-migration-writer.md) — agent invocado por `org-onboarding-implementer` para escrever migration
+- [supabase-edge-fn-writer](../../agents/supabase-edge-fn-writer.md) — agent invocado para escrever Edge Function setup wizard
+- [supabase-auth-ssr](../supabase-auth-ssr/SKILL.md) — middleware Next.js v16 que faz redirect 301 do slug history
+- [_shared-multi-tenant/glossary.md](../_shared-multi-tenant/glossary.md) — termos `tenant`, `org_id`, `first admin`, `bulk invite`