@plutocms/supabase 0.6.0 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.7.1](https://github.com/plutocms/supabase/compare/v0.7.0...v0.7.1) (2026-09-13)
+
+
+### Bug Fixes
+
+* **permissions:** break the migrations-page bootstrap deadlock ([#55](https://github.com/plutocms/supabase/issues/55)) ([19f4338](https://github.com/plutocms/supabase/commit/19f43388827ba1f4699a2347726e56084c06f8ef))
+
+## [0.7.0](https://github.com/plutocms/supabase/compare/v0.6.0...v0.7.0) (2026-09-12)
+
+
+### Features
+
+* **permissions:** add role-based capabilities, replacing single-bit admin ([#53](https://github.com/plutocms/supabase/issues/53)) ([72f2eb0](https://github.com/plutocms/supabase/commit/72f2eb051efe15e261d3c7fcef95bdf867e11f5a))
+
 ## [0.6.0](https://github.com/plutocms/supabase/compare/v0.5.0...v0.6.0) (2026-09-12)
 
 

package/FEATURES.md

@@ -8,3 +8,5 @@ policies shared by every project here.
 
 - Layer migrations: apply pending, versioned, per-file database migrations from the admin UI,
   after initial setup. @.claude/skills/layer-migrations/SKILL.md
+- Permissions storage: role-based capabilities backing server route guards and RLS policies.
+  @.claude/skills/permissions-storage/SKILL.md

package/app/pages/admin.vue

@@ -8,6 +8,20 @@ const route = useRoute()
 const { isLoggedIn, logout, allowedUnauthenticatedPaths } = await useAuth()
 const toast = useToast()
 
+const { load: loadPermissions, clear: clearPermissions } = usePlutoPermissions()
+
+watch(
+  isLoggedIn,
+  (loggedIn) => {
+    if (loggedIn) {
+      loadPermissions()
+    } else {
+      clearPermissions()
+    }
+  },
+  { immediate: true }
+)
+
 const visibility = useDocumentVisibility()
 
 watch(visibility, async (current, previous) => {

package/app/plugins/pluto-extension.ts

@@ -36,5 +36,19 @@ export default defineNuxtPlugin(() => {
         hasSettingsModified.value = Date.now()
       },
     },
+    // No 'system:migrate' capability: applying migrations stays admin-only,
+    // gated by requireAdmin (public.is_admin() directly), never a named
+    // capability — see server/utils/admin-guard.ts for why.
+    capabilities: [
+      { id: 'settings-manage', key: 'settings:manage', label: 'Manage site settings' },
+      { id: 'users-read', key: 'users:read', label: 'View all user accounts' },
+    ],
+    permissionsDriver: {
+      id: 'supabase',
+      load: async () => {
+        const response = await $fetch<{ capabilities: string[] }>('/api/permissions/me')
+        return response.capabilities
+      },
+    },
   })
 })

package/db/migrations/004_roles_and_capabilities.sql

@@ -0,0 +1,298 @@
+-- Roles and capabilities
+--
+-- Adds a role-based capability system. A role (public.roles) holds a set
+-- of capabilities (public.role_capabilities); a user (public.user_roles)
+-- holds a set of roles. public.has_capability(cap) answers "can the
+-- calling user do this?" for any layer's server routes and RLS policies.
+--
+-- Standalone and self-sufficient: it does not depend on running as a
+-- diff against another file, only on 001_baseline.sql's and
+-- 002_admin_hardening.sql's objects (public.profiles, public.settings,
+-- public.healthcheck, public.is_admin(), public.handle_new_user())
+-- already existing.
+
+-- Free text, never an enum. An enum would stop a layer, or an operator,
+-- from adding a role or a capability — the exact problem
+-- 003_settings_generic_keys.sql already fixed for settings.
+create table if not exists public.roles (
+  key text primary key,
+  label text not null,
+  description text,
+  is_builtin boolean not null default false,
+  created_at timestamptz not null default now(),
+  constraint roles_key_format check (key ~ '^[a-z0-9_]+$')
+);
+
+create table if not exists public.role_capabilities (
+  role_key text not null references public.roles (key) on delete cascade,
+  capability text not null,
+  primary key (role_key, capability),
+  -- '<namespace>:<action>', or the literal '*' for every capability.
+  constraint role_capabilities_format
+    check (capability = '*' or capability ~ '^[a-z0-9_]+:[a-z0-9_]+$')
+);
+
+create table if not exists public.user_roles (
+  user_id uuid not null references auth.users (id) on delete cascade,
+  role_key text not null references public.roles (key) on delete cascade,
+  granted_at timestamptz not null default now(),
+  primary key (user_id, role_key)
+);
+
+create index if not exists user_roles_user_id_idx on public.user_roles (user_id);
+
+-- Seed the built-in admin role, with the wildcard capability.
+insert into public.roles (key, label, description, is_builtin) values
+  ('admin', 'Administrator', 'Full access to every feature.', true)
+on conflict (key) do nothing;
+
+insert into public.role_capabilities (role_key, capability) values ('admin', '*')
+on conflict do nothing;
+
+-- Every existing admin gets the admin role with no manual step.
+insert into public.user_roles (user_id, role_key)
+select p.id, 'admin' from public.profiles p where p.is_admin = true
+on conflict do nothing;
+
+-- Returns true when the calling user holds the given capability, either
+-- directly through a role, or through public.is_admin(). SECURITY
+-- DEFINER for the same reason public.is_admin() is: the lookup must not
+-- be subject to the RLS policies it is being used to decide.
+create or replace function public.has_capability(cap text)
+returns boolean
+language sql security definer set search_path = '' stable
+as $$
+  select public.is_admin() or exists (
+    select 1
+      from public.user_roles ur
+      join public.role_capabilities rc on rc.role_key = ur.role_key
+     where ur.user_id = auth.uid()
+       and (rc.capability = cap or rc.capability = '*')
+  );
+$$;
+
+-- The flat capability list for the calling user. Backs /api/permissions/me.
+create or replace function public.my_capabilities()
+returns setof text
+language sql security definer set search_path = '' stable
+as $$
+  select '*'::text where public.is_admin()
+  union
+  select rc.capability
+    from public.user_roles ur
+    join public.role_capabilities rc on rc.role_key = ur.role_key
+   where ur.user_id = auth.uid();
+$$;
+
+grant execute on function public.has_capability(text) to authenticated;
+grant execute on function public.my_capabilities() to authenticated;
+
+-- Reimplements public.is_admin() to also recognize the 'admin' role, so
+-- every existing admin passes every new capability check automatically,
+-- with zero data migration. Kept as create or replace, not a new
+-- function: its name and signature (returns boolean, no arguments,
+-- language sql security definer set search_path = '', stable) never
+-- change. 30 RLS policies across 4 repos call it by name.
+create or replace function public.is_admin()
+returns boolean
+language sql
+security definer
+set search_path = ''
+stable
+as $$
+  select coalesce(
+    (select p.is_admin from public.profiles p where p.id = auth.uid()),
+    false
+  ) or exists (
+    select 1 from public.user_roles ur
+     where ur.user_id = auth.uid() and ur.role_key = 'admin'
+  );
+$$;
+
+-- Also grant the 'admin' role to a newly-created first-admin account, so
+-- has_capability() sees it the same way is_admin() does. Keeps the exact
+-- existing signature; on_auth_user_created (from 001_baseline.sql)
+-- already points at this function by name, and create or replace is
+-- enough to update its behavior.
+create or replace function public.handle_new_user()
+returns trigger
+language plpgsql
+security definer set search_path = ''
+as $$
+declare
+  profile_count int;
+  should_be_admin boolean;
+begin
+  select count(*) into profile_count from public.profiles;
+
+  -- Only the very first account is auto-promoted. Never trust
+  -- raw_user_meta_data for this: it is fully client-controlled — anyone can
+  -- pass an arbitrary `options.data` straight to Supabase's own
+  -- /auth/v1/signup endpoint, bypassing this project's own /api/auth/signup
+  -- route entirely — so honoring an `is_admin` key there let any new
+  -- signup grant itself admin.
+  should_be_admin := profile_count = 0;
+
+  insert into public.profiles (id, email, username, display_name, is_admin)
+  values (
+    new.id,
+    new.email,
+    new.raw_user_meta_data ->> 'username',
+    new.raw_user_meta_data ->> 'display_name',
+    should_be_admin
+  );
+
+  if should_be_admin then
+    insert into public.user_roles (user_id, role_key) values (new.id, 'admin')
+    on conflict do nothing;
+  end if;
+
+  return new;
+end;
+$$;
+
+-- RLS on the three new tables.
+alter table public.roles enable row level security;
+alter table public.role_capabilities enable row level security;
+alter table public.user_roles enable row level security;
+
+drop policy if exists "Enable read access for authenticated users on roles" on public.roles;
+
+create policy "Enable read access for authenticated users on roles"
+on public.roles
+for select
+to authenticated
+using (true);
+
+drop policy if exists "Enable insert for admins on roles" on public.roles;
+
+create policy "Enable insert for admins on roles"
+on public.roles
+for insert
+to authenticated
+with check (public.is_admin());
+
+drop policy if exists "Enable update for admins on roles" on public.roles;
+
+create policy "Enable update for admins on roles"
+on public.roles
+for update
+to authenticated
+using (public.is_admin())
+with check (public.is_admin());
+
+drop policy if exists "Enable delete for admins on roles" on public.roles;
+
+create policy "Enable delete for admins on roles"
+on public.roles
+for delete
+to authenticated
+using (public.is_admin());
+
+drop policy if exists "Enable read access for authenticated users on role_capabilities" on public.role_capabilities;
+
+create policy "Enable read access for authenticated users on role_capabilities"
+on public.role_capabilities
+for select
+to authenticated
+using (true);
+
+drop policy if exists "Enable insert for admins on role_capabilities" on public.role_capabilities;
+
+create policy "Enable insert for admins on role_capabilities"
+on public.role_capabilities
+for insert
+to authenticated
+with check (public.is_admin());
+
+drop policy if exists "Enable update for admins on role_capabilities" on public.role_capabilities;
+
+create policy "Enable update for admins on role_capabilities"
+on public.role_capabilities
+for update
+to authenticated
+using (public.is_admin())
+with check (public.is_admin());
+
+drop policy if exists "Enable delete for admins on role_capabilities" on public.role_capabilities;
+
+create policy "Enable delete for admins on role_capabilities"
+on public.role_capabilities
+for delete
+to authenticated
+using (public.is_admin());
+
+-- A user may always read their own role grants; only an admin reads
+-- everyone's. Every write is admin-only, with no exception: with check
+-- (true) here would let any authenticated user grant themselves the
+-- 'admin' role, a privilege-escalation hole identical in shape to the
+-- one closed in 002_admin_hardening.sql.
+drop policy if exists "Enable read access for own or admin on user_roles" on public.user_roles;
+
+create policy "Enable read access for own or admin on user_roles"
+on public.user_roles
+for select
+to authenticated
+using (user_id = auth.uid() or public.is_admin());
+
+drop policy if exists "Enable insert for admins on user_roles" on public.user_roles;
+
+create policy "Enable insert for admins on user_roles"
+on public.user_roles
+for insert
+to authenticated
+with check (public.is_admin());
+
+drop policy if exists "Enable update for admins on user_roles" on public.user_roles;
+
+create policy "Enable update for admins on user_roles"
+on public.user_roles
+for update
+to authenticated
+using (public.is_admin())
+with check (public.is_admin());
+
+drop policy if exists "Enable delete for admins on user_roles" on public.user_roles;
+
+create policy "Enable delete for admins on user_roles"
+on public.user_roles
+for delete
+to authenticated
+using (public.is_admin());
+
+-- Rewrite this repo's own three policies to named capabilities. Since
+-- has_capability() folds in is_admin() through the 'admin' role check,
+-- every existing admin is unaffected by this change.
+drop policy if exists "Enable read access for authenticated users" on public.profiles;
+
+create policy "Enable read access for authenticated users"
+on public.profiles
+for select
+to authenticated, dashboard_user
+using (auth.uid() = id or public.has_capability('users:read'));
+
+drop policy if exists "Enable insert for authenticated users only" on public.settings;
+
+create policy "Enable insert for authenticated users only"
+on public.settings
+for insert
+to authenticated, dashboard_user
+with check (public.has_capability('settings:manage'));
+
+drop policy if exists "Enable update for authenticated users on settings" on public.settings;
+
+create policy "Enable update for authenticated users on settings"
+on public.settings
+for update
+to authenticated, dashboard_user
+using (public.has_capability('settings:manage'))
+with check (public.has_capability('settings:manage'));
+
+drop policy if exists "Enable update for authenticated users on healthcheck" on public.healthcheck;
+
+create policy "Enable update for authenticated users on healthcheck"
+on public.healthcheck
+for update
+to authenticated, dashboard_user
+using (public.has_capability('settings:manage'))
+with check (public.has_capability('settings:manage'));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@plutocms/supabase",
   "type": "module",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "trustedDependencies": [
     "@parcel/watcher",
     "@plutocms/pluto",
@@ -39,7 +39,7 @@
     "@nuxt/eslint": "^1.16.0",
     "@nuxt/ui": "^4.9.0",
     "@nuxtjs/supabase": "^2.0.9",
-    "@plutocms/pluto": "^0.4.0",
+    "@plutocms/pluto": "^0.5.0",
     "@plutocms/utils": "^0.2.1",
     "postgres": "^3.4.9",
     "supabase": "^2.109.1"

package/server/api/migrations/run.post.ts

@@ -11,6 +11,9 @@ interface Payload {
 }
 
 export default defineEventHandler(async (event) => {
+  // requireAdmin specifically, not a named capability — see admin-guard.ts
+  // for why: this route must work even before 004_roles_and_capabilities.sql
+  // (which defines the capability system) has been applied.
   await requireAdmin(event)
 
   const body = await readBody<Payload | undefined>(event)

package/server/api/migrations/status.get.ts

@@ -2,6 +2,9 @@ import { requireAdmin } from '../../utils/admin-guard'
 import { getMigrationStatus } from '../../utils/pending-migrations'
 
 export default defineEventHandler(async (event) => {
+  // requireAdmin specifically, not a named capability — see admin-guard.ts
+  // for why: this route must work even before 004_roles_and_capabilities.sql
+  // (which defines the capability system) has been applied.
   await requireAdmin(event)
 
   const status = await getMigrationStatus(event)

package/server/api/permissions/me.get.ts

@@ -0,0 +1,35 @@
+import { serverSupabaseClient, serverSupabaseUser } from '#supabase/server'
+
+/**
+ * The calling user's own capability list. No admin gate — every signed-in
+ * user needs this to know what their own UI should show. A signed-out
+ * caller gets an empty list, not a 401, so the client composable never
+ * has to special-case this endpoint's error path.
+ */
+export default defineEventHandler(async (event) => {
+  const user = await serverSupabaseUser(event)
+
+  if (!user) {
+    return { capabilities: [] as string[] }
+  }
+
+  const client = await serverSupabaseClient<Database>(event)
+  const { data, error } = await client.rpc('my_capabilities')
+
+  if (error) {
+    // public.my_capabilities() is defined by 004_roles_and_capabilities.sql.
+    // A site that has upgraded this package but not yet applied that
+    // migration has no such function yet — that is an expected, temporary
+    // state during an upgrade, not a server error. Degrade to an empty
+    // capability list (the same shape a signed-out caller gets above)
+    // rather than 500ing: the caller already fails every can() check with
+    // an empty list, which is the correct, safe behavior until the pending
+    // migration is applied through /admin/migrations (itself gated by
+    // requireAdmin, not a capability, precisely so this state is always
+    // recoverable — see server/utils/admin-guard.ts).
+    console.error('my_capabilities() failed, returning an empty capability list:', error.message)
+    return { capabilities: [] as string[] }
+  }
+
+  return { capabilities: data ?? [] }
+})

package/server/api/settings/update.post.ts

@@ -1,5 +1,5 @@
 import { serverSupabaseClient } from '#supabase/server'
-import { requireAdmin } from '../../utils/admin-guard'
+import { requireCapability } from '../../utils/capability-guard'
 
 // A key is lowercase segments separated by dots, e.g. 'website_title' or
 // 'blog.posts_per_page'. Mirrors the settings_setting_key_format check
@@ -11,7 +11,7 @@ const SETTING_KEY_PATTERN = /^[a-z0-9_]+(?:\.[a-z0-9_]+)*$/
 const MAX_SETTING_VALUE_LENGTH = 10_000
 
 export default defineEventHandler(async (event) => {
-  await requireAdmin(event)
+  await requireCapability(event, 'settings:manage')
 
   const client = await serverSupabaseClient<Database>(event)
   const body = await readBody<Record<string, unknown>>(event)

package/server/api/users/[id].get.ts

@@ -1,8 +1,8 @@
 import { serverSupabaseClient } from '#supabase/server'
-import { requireAdmin } from '../../utils/admin-guard'
+import { requireCapability } from '../../utils/capability-guard'
 
 export default defineEventHandler(async (event) => {
-  await requireAdmin(event)
+  await requireCapability(event, 'users:read')
 
   const client = await serverSupabaseClient<Database>(event)
 

package/server/api/users/index.get.ts

@@ -1,8 +1,8 @@
 import { serverSupabaseClient } from '#supabase/server'
-import { requireAdmin } from '../../utils/admin-guard'
+import { requireCapability } from '../../utils/capability-guard'
 
 export default defineEventHandler(async (event) => {
-  await requireAdmin(event)
+  await requireCapability(event, 'users:read')
 
   const client = await serverSupabaseClient<Database>(event)
 

package/server/utils/admin-guard.ts

@@ -2,23 +2,27 @@ import type { H3Event } from 'h3'
 import { serverSupabaseClient, serverSupabaseUser } from '#supabase/server'
 
 /**
- * Guards a server route so only a logged-in admin can call it.
+ * Guards a server route so only an admin can call it.
  *
- * `serverSupabaseUser` (from `@nuxtjs/supabase`, backed by
- * `client.auth.getClaims()`) returns decoded JWT claims, not a Supabase
- * `User` row. The claims object has no `id` field — the user's id is the
- * `sub` claim. Using `user.id` here silently queries `eq('id', undefined)`,
- * which matches zero rows and looks exactly like "not an admin" even for a
- * real admin. Always read `user.sub`, never `user.id`.
- *
- * Reads `is_admin` from `public.profiles`, never from `user_metadata`. The
- * `handle_new_user` trigger never writes `is_admin` back to
- * `auth.users.raw_user_meta_data`, so `user_metadata.is_admin` can be unset
- * even for the first admin. `public.profiles.is_admin` is the source of
- * truth.
+ * Calls `public.is_admin()` directly — deliberately NOT through
+ * `requireCapability`/`public.has_capability()`. `has_capability()` is
+ * defined by `004_roles_and_capabilities.sql`; a site that has upgraded
+ * this package but not yet applied that migration has no such function in
+ * its database, and every `requireCapability` call would throw. If
+ * `requireAdmin` routed through it too, that would 403 the one route
+ * (`/api/migrations/*`) an admin needs to actually apply the migration —
+ * a deadlock with no escape through the UI. `public.is_admin()` has existed
+ * since `002_admin_hardening.sql` and is only ever `create or replace`d,
+ * never dropped, so it is always safe to call regardless of which layer
+ * migrations have been applied. This is also why the migrations routes
+ * call `requireAdmin` specifically, and not a named capability like
+ * `system:migrate` — migrations are a bootstrapping concern and must never
+ * depend on the capability system migrations themselves create.
  *
  * Throws a 401 if there is no logged-in user, or a 403 if the user is not
- * an admin. Returns the claims on success.
+ * an admin. Returns the user's claims on success. See capability-guard.ts
+ * for the same user.sub vs user.id note — this function has the same
+ * shape but never reads either field either.
  */
 export async function requireAdmin(event: H3Event) {
   const user = await serverSupabaseUser(event)
@@ -28,18 +32,10 @@ export async function requireAdmin(event: H3Event) {
   }
 
   const client = await serverSupabaseClient<Database>(event)
+  const { data, error } = await client.rpc('is_admin')
 
-  const { data: profile, error } = await client
-    .from('profiles')
-    .select('is_admin')
-    .eq('id', user.sub)
-    .single()
-
-  if (error || !profile?.is_admin) {
-    throw createError({
-      statusCode: 403,
-      statusMessage: 'Your account is not an admin.',
-    })
+  if (error || data !== true) {
+    throw createError({ statusCode: 403, statusMessage: 'Your account is not an admin.' })
   }
 
   return user

package/server/utils/capability-guard.ts

@@ -0,0 +1,52 @@
+import type { H3Event } from 'h3'
+import { serverSupabaseClient, serverSupabaseUser } from '#supabase/server'
+
+/** The wildcard capability. A holder passes every capability check. */
+export const ALL_CAPABILITIES = '*'
+
+interface RequireCapabilityOptions {
+  /** Overrides the 403 message. */
+  message?: string
+}
+
+/**
+ * Guards a server route on a named capability.
+ *
+ * `serverSupabaseUser` (from `@nuxtjs/supabase`, backed by
+ * `client.auth.getClaims()`) returns decoded JWT claims, not a Supabase
+ * `User` row — used here only to distinguish "not logged in" (401) from
+ * "logged in but missing the capability" (403). The capability check
+ * itself runs in the database, through public.has_capability(), a
+ * SECURITY DEFINER function that reads auth.uid() directly from the same
+ * session — user.sub/user.id is never passed to it.
+ *
+ * public.has_capability() folds in public.is_admin(), so every existing
+ * admin passes every capability check with no data migration.
+ *
+ * Throws a 401 if there is no logged-in user, or a 403 if the user is
+ * missing the capability. Returns the claims on success.
+ */
+export async function requireCapability(
+  event: H3Event,
+  capability: string,
+  options?: RequireCapabilityOptions
+) {
+  const user = await serverSupabaseUser(event)
+
+  if (!user) {
+    throw createError({ statusCode: 401, statusMessage: 'You must be logged in.' })
+  }
+
+  const client = await serverSupabaseClient<Database>(event)
+  const { data, error } = await client.rpc('has_capability', { cap: capability })
+
+  if (error || data !== true) {
+    throw createError({
+      statusCode: 403,
+      statusMessage:
+        options?.message ?? `Your account is missing the "${capability}" permission.`,
+    })
+  }
+
+  return user
+}

package/shared/types/supabase.ts

@@ -253,6 +253,53 @@ export type Database = {
         }
         Relationships: []
       }
+      role_capabilities: {
+        Row: {
+          capability: string
+          role_key: string
+        }
+        Insert: {
+          capability: string
+          role_key: string
+        }
+        Update: {
+          capability?: string
+          role_key?: string
+        }
+        Relationships: [
+          {
+            foreignKeyName: "role_capabilities_role_key_fkey"
+            columns: ["role_key"]
+            isOneToOne: false
+            referencedRelation: "roles"
+            referencedColumns: ["key"]
+          },
+        ]
+      }
+      roles: {
+        Row: {
+          created_at: string
+          description: string | null
+          is_builtin: boolean
+          key: string
+          label: string
+        }
+        Insert: {
+          created_at?: string
+          description?: string | null
+          is_builtin?: boolean
+          key: string
+          label: string
+        }
+        Update: {
+          created_at?: string
+          description?: string | null
+          is_builtin?: boolean
+          key?: string
+          label?: string
+        }
+        Relationships: []
+      }
       settings: {
         Row: {
           id: number
@@ -274,12 +321,49 @@ export type Database = {
         }
         Relationships: []
       }
+      user_roles: {
+        Row: {
+          granted_at: string
+          role_key: string
+          user_id: string
+        }
+        Insert: {
+          granted_at?: string
+          role_key: string
+          user_id: string
+        }
+        Update: {
+          granted_at?: string
+          role_key?: string
+          user_id?: string
+        }
+        Relationships: [
+          {
+            foreignKeyName: "user_roles_role_key_fkey"
+            columns: ["role_key"]
+            isOneToOne: false
+            referencedRelation: "roles"
+            referencedColumns: ["key"]
+          },
+        ]
+      }
     }
     Views: {
       [_ in never]: never
     }
     Functions: {
-      [_ in never]: never
+      has_capability: {
+        Args: { cap: string }
+        Returns: boolean
+      }
+      my_capabilities: {
+        Args: Record<PropertyKey, never>
+        Returns: string[]
+      }
+      is_admin: {
+        Args: Record<PropertyKey, never>
+        Returns: boolean
+      }
     }
     Enums: {
       thealthcheck: "first_setup"