-- Platform roles: owner / admin / moderator / support. -- Business architecture §2.1, §4.1 (profile_roles), §17.2 (helpers), §17.3. -- -- Platform roles are NOT professional statuses. practitioner / student / -- professor are outcomes of professional verification (identity step) and -- cabinet roles live in organization_members (organizations step). Keeping -- them out of this enum avoids a self-declared "practitioner" row ever being -- read as a verified status. -- -- Hierarchy for permission checks: owner ⊇ admin ⊇ moderator. support is -- separate and inherits nothing (§17.3 "Support does not inherit moderation"). -- Writes go through the two RPCs below only; the API roles cannot insert, -- update or delete rows. Revocation keeps the row (history), re-grant adds one. create type public.platform_role as enum ('owner', 'admin', 'moderator', 'support'); create table public.profile_roles ( id uuid primary key default gen_random_uuid(), user_id uuid not null references public.profiles (id) on delete cascade, role public.platform_role not null, granted_at timestamptz not null default now(), -- null = system (bootstrap, migration). granted_by uuid references public.profiles (id) on delete set null, revoked_at timestamptz, revoked_by uuid references public.profiles (id) on delete set null, revoke_reason text constraint profile_roles_revoke_reason_length check (char_length(revoke_reason) <= 500), -- revoked_by / revoke_reason only make sense on a revoked row. constraint profile_roles_revoke_consistent check (revoked_at is not null or (revoked_by is null and revoke_reason is null)) ); comment on table public.profile_roles is 'Platform role grants (owner/admin/moderator/support). One active row per (user, role); revoked rows kept as history. Writes only via grant_platform_role / revoke_platform_role.'; create unique index profile_roles_active_unique on public.profile_roles (user_id, role) where revoked_at is null; create index profile_roles_user_active_idx on public.profile_roles (user_id) where revoked_at is null; -- --------------------------------------------------------------------------- -- Helpers (security definer, read profile_roles bypassing its policies) -- --------------------------------------------------------------------------- create or replace function private.has_platform_role(p_user_id uuid, variadic p_roles public.platform_role[]) returns boolean language sql stable security definer set search_path = '' as $$ select exists ( select 1 from public.profile_roles r join public.profiles p on p.id = r.user_id where r.user_id = p_user_id and r.revoked_at is null and r.role = any (p_roles) and p.active ); $$; create or replace function private.is_platform_owner(p_user_id uuid) returns boolean language sql stable security definer set search_path = '' as $$ select private.has_platform_role(p_user_id, 'owner'); $$; create or replace function private.is_platform_admin(p_user_id uuid) returns boolean language sql stable security definer set search_path = '' as $$ select private.has_platform_role(p_user_id, 'owner', 'admin'); $$; create or replace function private.is_platform_moderator(p_user_id uuid) returns boolean language sql stable security definer set search_path = '' as $$ select private.has_platform_role(p_user_id, 'owner', 'admin', 'moderator'); $$; create or replace function private.is_support(p_user_id uuid) returns boolean language sql stable security definer set search_path = '' as $$ select private.has_platform_role(p_user_id, 'support'); $$; comment on function private.is_platform_admin(uuid) is 'true for owner or admin (active account).'; comment on function private.is_platform_moderator(uuid) is 'true for owner, admin or moderator (active account).'; comment on function private.is_support(uuid) is 'true for support only; support inherits nothing.'; -- Who may grant or revoke which role. owner: any role. admin: moderator, support. create or replace function private.can_manage_platform_role(p_actor uuid, p_role public.platform_role) returns boolean language sql stable security definer set search_path = '' as $$ select case when private.is_platform_owner(p_actor) then true when private.has_platform_role(p_actor, 'admin') then p_role in ('moderator', 'support') else false end; $$; -- Policies run as the API role: they need EXECUTE on the predicates. grant execute on function private.has_platform_role(uuid, public.platform_role[]) to authenticated; grant execute on function private.is_platform_owner(uuid) to authenticated; grant execute on function private.is_platform_admin(uuid) to authenticated; grant execute on function private.is_platform_moderator(uuid) to authenticated; grant execute on function private.is_support(uuid) to authenticated; -- can_manage_platform_role is called from the RPCs only (owner context). -- --------------------------------------------------------------------------- -- Internal write path (system or RPC), audited -- --------------------------------------------------------------------------- create or replace function private.assign_platform_role( p_actor uuid, p_target uuid, p_role public.platform_role ) returns uuid language plpgsql security definer set search_path = '' as $$ declare v_id uuid; begin if not exists (select 1 from public.profiles where id = p_target) then raise exception 'unknown user %', p_target using errcode = 'P0002'; end if; if exists ( select 1 from public.profile_roles where user_id = p_target and role = p_role and revoked_at is null ) then raise exception 'role % already granted to %', p_role, p_target using errcode = '23505'; end if; insert into public.profile_roles (user_id, role, granted_by) values (p_target, p_role, p_actor) returning id into v_id; perform private.log_event( p_actor, 'platform_role.granted', 'profile_role', v_id, p_target, null, jsonb_build_object('role', p_role) ); return v_id; end; $$; create or replace function private.withdraw_platform_role( p_actor uuid, p_target uuid, p_role public.platform_role, p_reason text ) returns uuid language plpgsql security definer set search_path = '' as $$ declare v_id uuid; begin select id into v_id from public.profile_roles where user_id = p_target and role = p_role and revoked_at is null; if v_id is null then raise exception 'role % is not active for %', p_role, p_target using errcode = 'P0002'; end if; -- Lock-out guard: the platform always keeps one active owner. if p_role = 'owner' and ( select count(*) from public.profile_roles where role = 'owner' and revoked_at is null ) <= 1 then raise exception 'cannot revoke the last platform owner' using errcode = '42501'; end if; update public.profile_roles set revoked_at = now(), revoked_by = p_actor, revoke_reason = p_reason where id = v_id; perform private.log_event( p_actor, 'platform_role.revoked', 'profile_role', v_id, p_target, null, jsonb_build_object('role', p_role, 'reason', p_reason) ); return v_id; end; $$; comment on function private.assign_platform_role(uuid, uuid, public.platform_role) is 'System write path. Bootstrap the first owner with p_actor = null from a privileged SQL session (docs/development/SUPABASE.md).'; -- --------------------------------------------------------------------------- -- RPCs (authenticated callers, checked against the actor's own roles) -- --------------------------------------------------------------------------- create or replace function public.grant_platform_role( target_user_id uuid, role public.platform_role ) returns uuid language plpgsql security definer set search_path = '' as $$ declare v_actor uuid := auth.uid(); begin if v_actor is null then raise exception 'authentication required' using errcode = '42501'; end if; if v_actor = target_user_id then raise exception 'a user cannot change their own platform roles' using errcode = '42501'; end if; if not private.can_manage_platform_role(v_actor, role) then raise exception 'insufficient privileges to grant role %', role using errcode = '42501'; end if; return private.assign_platform_role(v_actor, target_user_id, role); end; $$; create or replace function public.revoke_platform_role( target_user_id uuid, role public.platform_role, reason text default null ) returns uuid language plpgsql security definer set search_path = '' as $$ declare v_actor uuid := auth.uid(); begin if v_actor is null then raise exception 'authentication required' using errcode = '42501'; end if; if v_actor = target_user_id then raise exception 'a user cannot change their own platform roles' using errcode = '42501'; end if; if not private.can_manage_platform_role(v_actor, role) then raise exception 'insufficient privileges to revoke role %', role using errcode = '42501'; end if; return private.withdraw_platform_role(v_actor, target_user_id, role, reason); end; $$; comment on function public.grant_platform_role(uuid, public.platform_role) is 'Grants a platform role to another user. owner: any role; admin: moderator/support. Audited.'; comment on function public.revoke_platform_role(uuid, public.platform_role, text) is 'Revokes an active platform role of another user (same rights as grant). Keeps one owner. Audited.'; revoke all on function public.grant_platform_role(uuid, public.platform_role) from public, anon; revoke all on function public.revoke_platform_role(uuid, public.platform_role, text) from public, anon; grant execute on function public.grant_platform_role(uuid, public.platform_role) to authenticated, service_role; grant execute on function public.revoke_platform_role(uuid, public.platform_role, text) to authenticated, service_role; -- --------------------------------------------------------------------------- -- Privileges + RLS -- --------------------------------------------------------------------------- revoke all on public.profile_roles from public, anon, authenticated; grant select on public.profile_roles to authenticated; alter table public.profile_roles enable row level security; -- Own grants, or every grant for owners/admins. No write policy at all. create policy profile_roles_select_own_or_admin on public.profile_roles for select to authenticated using ( user_id = (select auth.uid()) or private.is_platform_admin((select auth.uid())) ); -- Staff read of profiles (owner/admin/support), now that the helpers exist. create policy profiles_select_staff on public.profiles for select to authenticated using ( private.is_platform_admin((select auth.uid())) or private.is_support((select auth.uid())) ); -- Audit log read: owners and admins. create policy audit_logs_select_admin on audit.audit_logs for select to authenticated using (private.is_platform_admin((select auth.uid())));