@plutocms/supabase 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [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)
+
+
+### Features
+
+* **settings:** generic, namespaced setting keys ([#51](https://github.com/plutocms/supabase/issues/51)) ([2410552](https://github.com/plutocms/supabase/commit/2410552ce6c880ecec1fac6f0b84852ef8612bea))
+
 ## [0.5.0](https://github.com/plutocms/supabase/compare/v0.4.1...v0.5.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/components/settings/SettingsGeneralPanel.vue

@@ -0,0 +1,30 @@
+<script setup lang="ts">
+const { field } = usePlutoSettings()
+
+const websiteTitle = field('website_title')
+const websiteDescription = field('website_description')
+const websiteUrl = field('website_url')
+</script>
+
+<template>
+  <div class="flex flex-col gap-y-6">
+    <UFormField label="Website Title" class="w-full lg:w-1/2">
+      <UInput v-model="websiteTitle" placeholder="e.g. My Website" />
+    </UFormField>
+
+    <UFormField label="Website Description" class="w-full lg:w-1/2">
+      <UInput
+        v-model="websiteDescription"
+        placeholder="e.g. My Website Description"
+      />
+    </UFormField>
+
+    <UFormField label="Website URL" class="w-full lg:w-1/2">
+      <UInput
+        v-model="websiteUrl"
+        type="url"
+        placeholder="e.g. https://example.com"
+      />
+    </UFormField>
+  </div>
+</template>

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

@@ -1,8 +1,52 @@
 import NavbarAdminProvider from '../components/navbar/NavbarAdminProvider.vue'
+import SettingsGeneralPanel from '../components/settings/SettingsGeneralPanel.vue'
 
 export default defineNuxtPlugin(() => {
   definePlutoExtension({
     id: 'supabase',
     navbar: { id: 'admin-navbar', component: NavbarAdminProvider },
+    settingsPanels: [
+      {
+        id: 'general',
+        order: 0,
+        title: 'General',
+        icon: 'lucide:globe',
+        component: SettingsGeneralPanel,
+      },
+    ],
+    settingsDriver: {
+      id: 'supabase',
+      load: async () => {
+        const response = await $fetch<{ settings: Record<string, string> }>(
+          '/api/settings'
+        )
+        return response.settings
+      },
+      save: async (patch) => {
+        await $fetch('/api/settings/update', {
+          method: 'POST',
+          body: patch,
+        })
+
+        // NavbarAdmin.vue watches this to refresh its own /api/settings
+        // read (it shows the site's own URL) — the settings page saving
+        // through the new registry must still trigger it, exactly like
+        // the old page did.
+        const hasSettingsModified = useState<number>('has_settings_modified')
+        hasSettingsModified.value = Date.now()
+      },
+    },
+    capabilities: [
+      { id: 'settings-manage', key: 'settings:manage', label: 'Manage site settings' },
+      { id: 'users-read', key: 'users:read', label: 'View all user accounts' },
+      { id: 'system-migrate', key: 'system:migrate', label: 'Apply pending layer migrations' },
+    ],
+    permissionsDriver: {
+      id: 'supabase',
+      load: async () => {
+        const response = await $fetch<{ capabilities: string[] }>('/api/permissions/me')
+        return response.capabilities
+      },
+    },
   })
 })

package/db/migrations/003_settings_generic_keys.sql

@@ -0,0 +1,37 @@
+-- Generic settings keys
+--
+-- public.settings has been a fixed 3-value enum since 001_baseline.sql —
+-- a layer other than @plutocms/supabase could never add its own setting
+-- without altering a shared type. This adds a free-text, namespaced key
+-- column alongside the enum column, without removing the enum column
+-- yet. Dropping setting_name and the TSettings enum is left for a later
+-- migration, once no shipped code writes it, to keep this one cheap to
+-- reason about and its effects easy to undo.
+--
+-- Key format: lowercase segments separated by dots, e.g. 'website_title'
+-- or 'blog.posts_per_page'. A layer other than core must namespace its
+-- keys with its own name, so two layers can never collide.
+
+alter table public.settings add column if not exists setting_key text;
+
+update public.settings set setting_key = setting_name::text where setting_key is null;
+
+alter table public.settings alter column setting_name drop not null;
+
+create unique index if not exists settings_setting_key_key on public.settings (setting_key);
+
+do $$
+begin
+  if not exists (
+    select 1 from pg_constraint
+     where conname = 'settings_setting_key_format'
+       and conrelid = 'public.settings'::regclass
+  ) then
+    alter table public.settings
+      add constraint settings_setting_key_format
+      check (setting_key ~ '^[a-z0-9_]+(?:\.[a-z0-9_]+)*$') not valid;
+  end if;
+end
+$$;
+
+alter table public.settings validate constraint settings_setting_key_format;

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/nuxt.config.ts

@@ -35,12 +35,6 @@ export default defineNuxtConfig({
     },
   },
 
-  vite: {
-    optimizeDeps: {
-      include: ['yup'],
-    },
-  },
-
   eslint: {
     config: {
       nuxt: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@plutocms/supabase",
   "type": "module",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "trustedDependencies": [
     "@parcel/watcher",
     "@plutocms/pluto",
@@ -39,11 +39,10 @@
     "@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",
-    "yup": "1.7.1"
+    "supabase": "^2.109.1"
   },
   "devDependencies": {
     "@antfu/eslint-config": "^6.2.0",

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

@@ -1,6 +1,6 @@
 import type { PlutoMigrationFile } from '../../../shared/types/migrations'
 import type { MigrationFileResult } from '../../utils/migrations'
-import { requireAdmin } from '../../utils/admin-guard'
+import { requireCapability } from '../../utils/capability-guard'
 import { persistDatabaseUrl } from '../../utils/env-file'
 import { resolveConnectionString, runPendingMigrations } from '../../utils/migrations'
 import { scrubConnectionString } from '../../utils/scrub-connection-string'
@@ -11,7 +11,7 @@ interface Payload {
 }
 
 export default defineEventHandler(async (event) => {
-  await requireAdmin(event)
+  await requireCapability(event, 'system:migrate')
 
   const body = await readBody<Payload | undefined>(event)
 

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

@@ -1,8 +1,8 @@
-import { requireAdmin } from '../../utils/admin-guard'
+import { requireCapability } from '../../utils/capability-guard'
 import { getMigrationStatus } from '../../utils/pending-migrations'
 
 export default defineEventHandler(async (event) => {
-  await requireAdmin(event)
+  await requireCapability(event, 'system:migrate')
 
   const status = await getMigrationStatus(event)
 

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

@@ -0,0 +1,24 @@
+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) {
+    throw createError({ statusCode: 500, statusMessage: error.message })
+  }
+
+  return { capabilities: data ?? [] }
+})

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

@@ -3,24 +3,23 @@ import { serverSupabaseClient } from '#supabase/server'
 export default defineEventHandler(async (event) => {
   const client = await serverSupabaseClient<Database>(event)
 
-  const { data } = await client.from('settings').select('*')
+  const { data } = await client
+    .from('settings')
+    .select('setting_key, setting_name, setting_value')
 
-  type SettingsKey =
-    Database['public']['Tables']['settings']['Row']['setting_name']
-
-  // @ts-expect-error: Object.fromEntries may not infer the correct type for settings
-  const settings: Record<SettingsKey, string> = {
-    ...Object.fromEntries(
-      data?.map((item) => [item.setting_name, item.setting_value]) || []
-    ),
-  }
+  const settings: Record<string, string> = {}
 
   data?.forEach((item) => {
-    if (!item.setting_name || !item.setting_value) {
+    // setting_key is null only for a row written before
+    // db/migrations/003_settings_generic_keys.sql backfilled it — fall
+    // back to the enum column so a mid-migration read never drops a row.
+    const key = item.setting_key ?? item.setting_name
+
+    if (!key || !item.setting_value) {
       return
     }
 
-    settings[item.setting_name] = item.setting_value
+    settings[key] = item.setting_value
   })
 
   return { settings }

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

@@ -1,36 +1,30 @@
 import { serverSupabaseClient } from '#supabase/server'
-import { requireAdmin } from '../../utils/admin-guard'
+import { requireCapability } from '../../utils/capability-guard'
 
-// Mirrors the TSettings enum in db/migrations/001_baseline.sql. The Postgres enum
-// already rejects an unknown key at the DB level (as a raw constraint
-// error) — this turns that into a clean 400 instead.
-const KNOWN_SETTING_KEYS = [
-  'website_title',
-  'website_url',
-  'website_description',
-] as const
+// A key is lowercase segments separated by dots, e.g. 'website_title' or
+// 'blog.posts_per_page'. Mirrors the settings_setting_key_format check
+// constraint in db/migrations/003_settings_generic_keys.sql — this turns
+// a violation into a clean 400 instead of a raw Postgres error. A layer
+// other than core must namespace its own keys so two layers can never
+// collide.
+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)
-
-  type SettingName =
-    Database['public']['Tables']['settings']['Insert']['setting_name']
-  type FormBody = Record<SettingName, string>
+  await requireCapability(event, 'settings:manage')
 
   const client = await serverSupabaseClient<Database>(event)
-  const body = await readBody<FormBody>(event)
+  const body = await readBody<Record<string, unknown>>(event)
 
   if (!body || typeof body !== 'object') {
     throw createError({ statusCode: 400, statusMessage: 'No payload sent.' })
   }
 
   const transformed = Object.entries(body).map(([key, value]) => {
-    if (
-      !KNOWN_SETTING_KEYS.includes(key as (typeof KNOWN_SETTING_KEYS)[number])
-    ) {
+    if (!SETTING_KEY_PATTERN.test(key)) {
       throw createError({
         statusCode: 400,
-        statusMessage: `Unknown setting: ${key}`,
+        statusMessage: `Invalid setting key: ${key}`,
       })
     }
 
@@ -41,15 +35,22 @@ export default defineEventHandler(async (event) => {
       })
     }
 
+    if (value.length > MAX_SETTING_VALUE_LENGTH) {
+      throw createError({
+        statusCode: 400,
+        statusMessage: `Setting "${key}" is too long.`,
+      })
+    }
+
     return {
-      setting_name: key as SettingName,
+      setting_key: key,
       setting_value: value,
     }
   })
 
   const { data, error } = await client
     .from('settings')
-    .upsert(transformed, { onConflict: 'setting_name' })
+    .upsert(transformed, { onConflict: 'setting_key' })
     .select()
 
   if (error) {

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

@@ -1,46 +1,19 @@
 import type { H3Event } from 'h3'
-import { serverSupabaseClient, serverSupabaseUser } from '#supabase/server'
+import { ALL_CAPABILITIES, requireCapability } from './capability-guard'
 
 /**
- * Guards a server route so only a logged-in 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.
+ * Guards a server route so only an admin (or a holder of every
+ * capability, which is what the built-in admin role grants) can call it.
+ * A thin alias over requireCapability, kept for the routes that ask for
+ * "admin, full stop" rather than one named capability.
  *
  * 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 claims on success. See capability-guard.ts for
+ * the user.sub vs user.id note: this function forwards straight into
+ * requireCapability, which never reads either field.
  */
 export async function requireAdmin(event: H3Event) {
-  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: 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.',
-    })
-  }
-
-  return user
+  return requireCapability(event, ALL_CAPABILITIES, {
+    message: 'Your account is not an admin.',
+  })
 }

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,30 +253,113 @@ 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
-          setting_name: Database["public"]["Enums"]["tsettings"]
+          setting_key: string | null
+          setting_name: Database["public"]["Enums"]["tsettings"] | null
           setting_value: string
         }
         Insert: {
           id?: number
-          setting_name: Database["public"]["Enums"]["tsettings"]
+          setting_key?: string | null
+          setting_name?: Database["public"]["Enums"]["tsettings"] | null
           setting_value: string
         }
         Update: {
           id?: number
-          setting_name?: Database["public"]["Enums"]["tsettings"]
+          setting_key?: string | null
+          setting_name?: Database["public"]["Enums"]["tsettings"] | null
           setting_value?: string
         }
         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[]
+      }
     }
     Enums: {
       thealthcheck: "first_setup"

package/app/pages/admin/settings.vue

@@ -1,125 +0,0 @@
-<script setup lang="ts">
-import { object, string } from 'yup'
-
-type Form = Partial<
-  Record<
-    Database['public']['Tables']['settings']['Insert']['setting_name'],
-    string
-  >
->
-
-useHead({
-  title: 'Settings',
-})
-
-const toast = useToast()
-
-const has_settings_modified = useState('has_settings_modified', () => {
-  return Date.now()
-})
-
-const { data } = await useFetch('/api/settings')
-
-const schema = object({
-  website_title: string().required().label('Website Title'),
-  website_description: string().required().label('Website Description'),
-  website_url: string().url().required().label('Website URL'),
-})
-
-const form = ref<Form>({
-  website_title: data.value?.settings.website_title || '',
-  website_description: data.value?.settings.website_description || '',
-  website_url: data.value?.settings.website_url || '',
-})
-
-const isSubmitting = ref<boolean>(false)
-
-async function submitForm() {
-  const payload = form.value
-
-  isSubmitting.value = true
-
-  try {
-    await $fetch('/api/settings/update', {
-      method: 'POST',
-      body: payload,
-    })
-
-    toast.add({
-      title: 'Settings updated successfully',
-      color: 'success',
-    })
-
-    has_settings_modified.value = Date.now()
-  } catch (error) {
-    if (import.meta.dev) {
-      console.error('Error updating settings:', error)
-    }
-
-    toast.add({
-      title: 'Failed to update settings.',
-      color: 'error',
-    })
-  } finally {
-    isSubmitting.value = false
-  }
-}
-</script>
-
-<template>
-  <AdminView>
-    <h1 class="text-3xl font-bold lg:text-4xl">Settings</h1>
-
-    <UCard>
-      <UForm :schema="schema" :state="form" @submit="submitForm">
-        <div class="flex flex-col gap-y-6">
-          <UFormField
-            label="Website Title"
-            name="website_title"
-            class="w-full lg:w-1/2"
-          >
-            <UInput
-              v-model="form.website_title"
-              placeholder="e.g. My Website"
-            />
-          </UFormField>
-
-          <UFormField
-            label="Website Description"
-            name="website_description"
-            class="w-full lg:w-1/2"
-          >
-            <UInput
-              v-model="form.website_description"
-              placeholder="e.g. My Website Description"
-            />
-          </UFormField>
-
-          <UFormField
-            label="Website URL"
-            name="website_url"
-            class="w-full lg:w-1/2"
-          >
-            <UInput
-              v-model="form.website_url"
-              type="url"
-              placeholder="e.g. https://example.com"
-            />
-          </UFormField>
-
-          <div class="flex">
-            <UButton
-              :loading="isSubmitting"
-              :disabled="isSubmitting"
-              type="submit"
-              icon="lucide:save"
-              class="w-full justify-center sm:w-auto"
-            >
-              Save
-            </UButton>
-          </div>
-        </div>
-      </UForm>
-    </UCard>
-  </AdminView>
-</template>