@plutocms/supabase 0.11.2 → 0.12.0

package/.env.example

@@ -1,2 +1,16 @@
 SUPABASE_URL=
 SUPABASE_KEY=
+
+# Optional run-time secret of the server. With it, invites use Supabase's
+# invite API and the "Invite user" email. Without it, invites send a
+# sign-in link. Set it in the environment of the running server only.
+# Never put it in the build environment, and never commit it.
+# NUXT_SUPABASE_SECRET_KEY=
+
+# Optional Pluto mail (run-time secrets of the server, never in the build
+# environment). With the service role key above AND a working mail driver,
+# invites go out through Pluto mail, not through Supabase's mailer. Set these
+# in the environment of the running server. See the `mail` skill of
+# @plutocms/pluto for every variable.
+# NUXT_PLUTO_MAIL_RESEND_API_KEY=
+# NUXT_PLUTO_MAIL_FROM="Your Site <hello@your-domain.com>"

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.12.0](https://github.com/plutocms/supabase/compare/v0.11.3...v0.12.0) (2026-10-25)
+
+
+### Features
+
+* **access:** manage users and roles, with invites through Pluto mail ([#98](https://github.com/plutocms/supabase/issues/98)) ([0d2ffbf](https://github.com/plutocms/supabase/commit/0d2ffbf0b3f7ad14e1ceeac6e396e01a6bb63279))
+
+## [0.11.3](https://github.com/plutocms/supabase/compare/v0.11.2...v0.11.3) (2026-10-22)
+
+
+### Bug Fixes
+
+* **permissions:** treat a profile admin as admin when my_capabilities() is missing ([#96](https://github.com/plutocms/supabase/issues/96)) ([f0e4980](https://github.com/plutocms/supabase/commit/f0e49808d0a7ceb9ffec45947e9ba5a1a033b9aa))
+
 ## [0.11.2](https://github.com/plutocms/supabase/compare/v0.11.1...v0.11.2) (2026-10-22)
 
 

package/FEATURES.md

@@ -8,8 +8,12 @@ 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.
+- Permissions storage: role-based capabilities backing server route guards and RLS policies, and
+  the admin-only access API (invite, roles) of migration 008.
   @.claude/skills/permissions-storage/SKILL.md
+- Users and Roles: the Users and Roles tabs of Settings (invite, edit roles, revoke, copy invite
+  link, roles editor), invites through Pluto mail, and a guide for the Supabase sign-in emails.
+  @.claude/skills/users-and-roles/SKILL.md
 - Content adapter: a Supabase/PostgREST-backed `PlutoContentAdapter`, plugging any layer's
   declared content type into `@plutocms/pluto`'s generic content routes.
   @.claude/skills/content-adapter/SKILL.md

package/README.md

@@ -56,6 +56,64 @@ top navbar. This layer registers an auth driver, and core renders the shell from
 An app that overrode `NavbarAdmin` or `pages/admin.vue` of an older version must move to registry
 entries. See "Migrating an app" in that skill.
 
+### Invite users (access API)
+
+An admin invites a user by email and gives the user one or more roles. The routes are under
+`/api/access/**`. Every write needs an admin. This needs the migration
+`008_users_and_roles_admin.sql`, which the admin applies from `/admin/migrations`.
+
+Invites need no setup. Check one thing: in the Supabase dashboard (Authentication, then URL
+Configuration), the **Site URL** is the URL of your site. Supabase accepts every link back to that
+host, so `/admin/accept-invite` needs no entry in the Redirect URLs. Add a Redirect URL only for
+another host (for example a preview deploy, or `www.` next to the bare domain).
+
+How the invite email goes out:
+
+- **Without the service role key** (the default): the server sends a passwordless sign-in link
+  with the public key. Supabase creates the account and uses its sign-up or magic link email
+  template. Public sign-up must be on (the Supabase default). Supabase sends one email per
+  address every 60 seconds.
+- **With the service role key** (optional): set `NUXT_SUPABASE_SECRET_KEY` (the Supabase secret
+  key) in the environment of the **running server**. Never put it in the build environment. The
+  server then uses Supabase's invite API and the "Invite user" email template. This also works
+  when public sign-up is off.
+
+Optional: a custom invite email template (Authentication, then Email Templates, then Invite
+user) makes the link work in every browser, because the page then reads a `token_hash` and not
+tokens in the URL hash:
+
+```
+{{ .SiteURL }}/admin/accept-invite?token_hash={{ .TokenHash }}&type=invite
+```
+
+The built-in Supabase mailer sends very few emails, and only to members of your Supabase
+organization. To invite any other address, set up custom SMTP (Project Settings, then
+Authentication, then SMTP). A production site needs it anyway, for every auth email. Without it,
+an invite to another address answers 400 with the hint `emailNotAuthorized`.
+
+The invited user opens the link, sets a password on `/admin/accept-invite`, and goes to the
+admin. An invite to an email that already has an account adds the roles and sends no email.
+
+#### Invites through Pluto mail (optional)
+
+With the service role key **and** a working Pluto mail driver, an invite does not use Supabase's
+mailer. The server makes a one-time link with `auth.admin.generateLink`, and Pluto mail sends the
+email. This lifts the team-only address rule and the Supabase email rate limit for invites. Set
+the mail variables in the environment of the **running server** (Resend is the first driver):
+
+```
+NUXT_PLUTO_MAIL_RESEND_API_KEY=re_...
+NUXT_PLUTO_MAIL_FROM="Your Site <hello@your-domain.com>"
+```
+
+`Settings > Email` in the admin guides the setup (account, key, domain, test email). The
+`mail` skill of `@plutocms/pluto` lists every `NUXT_PLUTO_MAIL_*` variable. If the send fails,
+the user and the roles stay, and the admin gets the invite link to send by hand.
+
+With the key, an admin can also copy the invite link (Users, then the row menu, or the invite
+form). The link works once and expires. Sign-up, password reset and magic link emails still
+come from Supabase. The Email tab has a guide to send them through Resend too.
+
 ### API Routes
 
 The layer includes API routes for interacting with Supabase services, such as authentication and media management.
@@ -63,6 +121,14 @@ The layer includes API routes for interacting with Supabase services, such as au
 - GET `/api/settings`
 - POST `/api/settings/update`
 - POST `/api/auth/signup`
+- GET `/api/access/users`, GET `/api/access/roles` (permission `users:read`)
+- POST `/api/access/users/invite`, POST `/api/access/users/:id/resend` (admin; `locale` is the
+  optional language of the email)
+- POST `/api/access/users/invite-link` (admin; needs the service role key; returns a one-time link
+  and sends no email)
+- GET `/api/access/capabilities` (admin; says whether the service key and Pluto mail are set)
+- PUT and DELETE `/api/access/users/:id/roles` (admin; DELETE revokes the access)
+- POST `/api/access/roles`, PUT and DELETE `/api/access/roles/:key` (admin)
 
 ### Types
 

package/app/components/access/CopyButton.vue

@@ -0,0 +1,24 @@
+<script setup lang="ts">
+// A small button that copies a text. The tooltip says "Copied" for 2 seconds.
+const props = defineProps<{
+  text: string
+  /** The accessible name of the button. */
+  label: string
+}>()
+
+const { t } = usePlutoI18n()
+const { copy, copied } = useClipboard({ copiedDuring: 2000 })
+</script>
+
+<template>
+  <UTooltip :text="copied ? t('supabase.access.link.copied') : props.label">
+    <UButton
+      :icon="copied ? 'lucide:check' : 'lucide:copy'"
+      :aria-label="props.label"
+      :color="copied ? 'success' : 'neutral'"
+      variant="ghost"
+      size="xs"
+      @click="copy(props.text)"
+    />
+  </UTooltip>
+</template>

package/app/components/access/DeleteRoleModal.vue

@@ -0,0 +1,73 @@
+<script setup lang="ts">
+// Confirms and deletes a role. It says how many users lose the role. Opened
+// with useOverlay from the Roles page.
+import type { AccessRole } from '../../../shared/types/access'
+
+const props = defineProps<{
+  role: AccessRole
+}>()
+
+const emit = defineEmits<{ close: [deleted: boolean] }>()
+
+const { t } = usePlutoI18n()
+const toast = useToast()
+const errorText = usePlutoErrorText()
+
+const working = ref(false)
+
+async function remove() {
+  if (working.value) {
+    return
+  }
+
+  working.value = true
+
+  try {
+    await $fetch(`/api/access/roles/${props.role.key}`, { method: 'DELETE' })
+
+    toast.add({
+      title: t('supabase.access.toasts.roleDeleted'),
+      color: 'success',
+      icon: 'lucide:circle-check',
+    })
+    emit('close', true)
+  } catch (error) {
+    toast.add({
+      title: t('supabase.access.toasts.failed'),
+      description: errorText(error),
+      color: 'error',
+      icon: 'lucide:circle-x',
+    })
+  } finally {
+    working.value = false
+  }
+}
+</script>
+
+<template>
+  <UModal
+    :title="t('supabase.access.deleteRole.title')"
+    :description="t('supabase.access.deleteRole.body', { name: role.label })"
+    :close="{ onClick: () => emit('close', false) }"
+  >
+    <template #body>
+      <UAlert
+        :description="t('supabase.access.deleteRole.usersLose', role.user_count)"
+        :color="role.user_count > 0 ? 'warning' : 'neutral'"
+        variant="subtle"
+        icon="lucide:users"
+      />
+    </template>
+
+    <template #footer>
+      <div class="flex w-full justify-end gap-2">
+        <UButton color="neutral" variant="outline" @click="emit('close', false)">
+          {{ t('pluto.common.cancel') }}
+        </UButton>
+        <UButton :loading="working" color="error" icon="lucide:trash-2" @click="remove">
+          {{ t('supabase.access.deleteRole.confirm') }}
+        </UButton>
+      </div>
+    </template>
+  </UModal>
+</template>

package/app/components/access/EditRolesSlideover.vue

@@ -0,0 +1,134 @@
+<script setup lang="ts">
+// Changes the roles of one user. The save replaces the roles. A change to the
+// roles of the signed-in admin loads the permissions again, so the menu and
+// the tabs follow at once.
+import type { AccessRole, AccessUser } from '../../../shared/types/access'
+import { ADMIN_ROLE_KEY, sameKeys, userDisplayName } from '../../utils/access-ui'
+
+const props = defineProps<{
+  user: AccessUser | null
+  roles: AccessRole[]
+  /** True when the user is the signed-in admin. */
+  self: boolean
+}>()
+
+const emit = defineEmits<{ saved: [] }>()
+
+const open = defineModel<boolean>('open', { required: true })
+
+const { t } = usePlutoI18n()
+const toast = useToast()
+const errorText = usePlutoErrorText()
+const permissions = usePlutoPermissions()
+
+const roleKeys = ref<string[]>([])
+const saving = ref(false)
+
+watch(
+  () => [open.value, props.user?.id] as const,
+  ([isOpen]) => {
+    if (isOpen && props.user) {
+      roleKeys.value = [...props.user.roles]
+    }
+  },
+  { immediate: true }
+)
+
+const items = computed(() =>
+  props.roles.map((role) => ({
+    label: role.label,
+    value: role.key,
+    description: role.description || undefined,
+  }))
+)
+
+const name = computed(() => (props.user ? userDisplayName(props.user) : ''))
+const unchanged = computed(() => !props.user || sameKeys(roleKeys.value, props.user.roles))
+
+// The warning shows when the admin removes their own admin role.
+const removesOwnAdmin = computed(
+  () =>
+    props.self
+    && (props.user?.roles.includes(ADMIN_ROLE_KEY) ?? false)
+    && !roleKeys.value.includes(ADMIN_ROLE_KEY)
+)
+
+async function save() {
+  if (!props.user || saving.value || roleKeys.value.length === 0) {
+    return
+  }
+
+  saving.value = true
+
+  try {
+    await $fetch(`/api/access/users/${props.user.id}/roles`, {
+      method: 'PUT',
+      body: { roleKeys: roleKeys.value },
+    })
+
+    toast.add({
+      title: t('supabase.access.toasts.rolesSaved'),
+      color: 'success',
+      icon: 'lucide:circle-check',
+    })
+
+    if (props.self) {
+      await permissions.load()
+    }
+
+    emit('saved')
+    open.value = false
+  } catch (error) {
+    toast.add({
+      title: t('supabase.access.toasts.failed'),
+      description: errorText(error),
+      color: 'error',
+      icon: 'lucide:circle-x',
+    })
+  } finally {
+    saving.value = false
+  }
+}
+</script>
+
+<template>
+  <USlideover
+    v-model:open="open"
+    :title="t('supabase.access.editRoles.title')"
+    :description="t('supabase.access.editRoles.description', { name })"
+  >
+    <template #body>
+      <div class="flex flex-col gap-y-4">
+        <UAlert
+          v-if="removesOwnAdmin"
+          :description="t('supabase.access.editRoles.selfAdmin')"
+          color="warning"
+          variant="subtle"
+          icon="lucide:triangle-alert"
+        />
+
+        <UCheckboxGroup v-model="roleKeys" :items="items" />
+
+        <p v-if="roleKeys.length === 0" class="text-muted text-sm">
+          {{ t('supabase.access.editRoles.emptyHint') }}
+        </p>
+      </div>
+    </template>
+
+    <template #footer>
+      <div class="flex w-full justify-end gap-2">
+        <UButton color="neutral" variant="outline" @click="open = false">
+          {{ t('pluto.common.cancel') }}
+        </UButton>
+        <UButton
+          :loading="saving"
+          :disabled="unchanged || roleKeys.length === 0"
+          icon="lucide:save"
+          @click="save"
+        >
+          {{ t('supabase.access.editRoles.save') }}
+        </UButton>
+      </div>
+    </template>
+  </USlideover>
+</template>

package/app/components/access/InviteModal.vue

@@ -0,0 +1,288 @@
+<script setup lang="ts">
+// The invite form. It sends the invite, or copies the invite link when the
+// server has the service role key. When Supabase's mailer refuses the invite
+// (a team-only address, a rate limit, a bad address), an inline alert shows the
+// cause with two ways out: copy the link, or set up email.
+import type {
+  AccessCapabilities,
+  AccessInviteResult,
+  AccessRole,
+} from '../../../shared/types/access'
+import { isInviteMailError, languageName } from '../../utils/access-ui'
+
+const props = defineProps<{
+  roles: AccessRole[]
+  /** What the server offers. Null while it is not known. */
+  capabilities: AccessCapabilities | null
+}>()
+
+const emit = defineEmits<{ done: [] }>()
+
+const open = defineModel<boolean>('open', { required: true })
+
+const { t, locale, locales } = usePlutoI18n()
+const toast = useToast()
+const errorText = usePlutoErrorText()
+
+const email = ref('')
+const name = ref('')
+const roleKeys = ref<string[]>([])
+const emailLocale = ref(locale.value)
+const submitting = ref(false)
+const showRolesError = ref(false)
+// The cause shown in the inline alert, when the mailer refused the invite.
+const mailProblem = ref<string | null>(null)
+// The link of the finished invite, when the user must send it by hand.
+const link = ref<string | null>(null)
+
+const roleItems = computed(() =>
+  props.roles.map((role) => ({
+    label: role.label,
+    value: role.key,
+    description: role.description || undefined,
+  }))
+)
+
+const localeItems = computed(() =>
+  locales.value.map((code) => ({ label: languageName(code), value: code }))
+)
+
+const canCopyLink = computed(() => props.capabilities?.serviceKey === true)
+
+// A fresh form each time the modal opens.
+watch(open, (isOpen) => {
+  if (isOpen) {
+    email.value = ''
+    name.value = ''
+    roleKeys.value = []
+    emailLocale.value = locale.value
+    showRolesError.value = false
+    mailProblem.value = null
+    link.value = null
+  }
+})
+
+function body() {
+  return {
+    email: email.value.trim(),
+    roleKeys: roleKeys.value,
+    displayName: name.value.trim() || undefined,
+  }
+}
+
+function valid(): boolean {
+  showRolesError.value = roleKeys.value.length === 0
+
+  return !showRolesError.value
+}
+
+async function submit() {
+  if (submitting.value || !valid()) {
+    return
+  }
+
+  submitting.value = true
+  mailProblem.value = null
+
+  try {
+    const result = await $fetch<AccessInviteResult>('/api/access/users/invite', {
+      method: 'POST',
+      body: { ...body(), locale: emailLocale.value },
+    })
+
+    emit('done')
+
+    if (result.status === 'granted') {
+      toast.add({
+        title: t('supabase.access.toasts.granted', { email: email.value.trim() }),
+        color: 'success',
+        icon: 'lucide:circle-check',
+      })
+      open.value = false
+    } else if (result.emailSent === false && result.link) {
+      // The user exists and has the roles. Only the email failed.
+      link.value = result.link
+      toast.add({
+        title: t('supabase.access.toasts.emailFailed', { email: email.value.trim() }),
+        color: 'warning',
+        icon: 'lucide:triangle-alert',
+      })
+    } else {
+      toast.add({
+        title: t('supabase.access.toasts.invited', { email: email.value.trim() }),
+        color: 'success',
+        icon: 'lucide:circle-check',
+      })
+      open.value = false
+    }
+  } catch (error) {
+    if (isInviteMailError(error)) {
+      mailProblem.value = errorText(error)
+    } else {
+      toast.add({
+        title: t('supabase.access.toasts.failed'),
+        description: errorText(error),
+        color: 'error',
+        icon: 'lucide:circle-x',
+      })
+    }
+  } finally {
+    submitting.value = false
+  }
+}
+
+async function copyLink() {
+  if (submitting.value || !valid()) {
+    return
+  }
+
+  submitting.value = true
+
+  try {
+    const result = await $fetch<{ status: 'invited' | 'granted', link: string | null }>(
+      '/api/access/users/invite-link',
+      { method: 'POST', body: body() }
+    )
+
+    mailProblem.value = null
+    emit('done')
+
+    // A confirmed account gets no link: it signs in with its own password.
+    if (!result.link) {
+      toast.add({
+        title: t('supabase.access.toasts.granted', { email: body().email }),
+        color: 'success',
+        icon: 'lucide:circle-check',
+      })
+      open.value = false
+      return
+    }
+
+    link.value = result.link
+  } catch (error) {
+    toast.add({
+      title: t('supabase.access.toasts.failed'),
+      description: errorText(error),
+      color: 'error',
+      icon: 'lucide:circle-x',
+    })
+  } finally {
+    submitting.value = false
+  }
+}
+
+async function setupEmail() {
+  open.value = false
+  await navigateTo('/admin/settings/email?reason=invite')
+}
+</script>
+
+<template>
+  <UModal
+    v-model:open="open"
+    :title="link ? t('supabase.access.invite.linkTitle') : t('supabase.access.invite.title')"
+    :description="link ? t('supabase.access.invite.linkDescription') : t('supabase.access.invite.description')"
+  >
+    <template #body>
+      <AccessLinkField v-if="link" :link="link" />
+
+      <form v-else class="flex flex-col gap-y-4" @submit.prevent="submit">
+        <UAlert
+          v-if="mailProblem"
+          :title="t('supabase.access.invite.mailProblem')"
+          :description="mailProblem"
+          color="warning"
+          variant="subtle"
+          icon="lucide:mail-warning"
+        >
+          <template #actions>
+            <UButton
+              v-if="canCopyLink"
+              :loading="submitting"
+              color="neutral"
+              variant="outline"
+              size="xs"
+              icon="lucide:link"
+              @click="copyLink"
+            >
+              {{ t('supabase.access.invite.copyLink') }}
+            </UButton>
+            <UButton
+              color="neutral"
+              variant="outline"
+              size="xs"
+              icon="lucide:settings"
+              @click="setupEmail"
+            >
+              {{ t('supabase.access.invite.setupEmail') }}
+            </UButton>
+          </template>
+        </UAlert>
+
+        <p
+          v-if="mailProblem && !canCopyLink"
+          class="text-muted text-sm"
+        >
+          {{ t('supabase.access.invite.needsKey') }}
+        </p>
+
+        <UFormField :label="t('supabase.access.invite.email')" required>
+          <UInput
+            v-model="email"
+            :placeholder="t('supabase.access.invite.emailPlaceholder')"
+            type="email"
+            autocomplete="off"
+            class="w-full"
+            required
+          />
+        </UFormField>
+
+        <UFormField :label="t('supabase.access.invite.name')">
+          <UInput
+            v-model="name"
+            :placeholder="t('supabase.access.invite.namePlaceholder')"
+            autocomplete="off"
+            class="w-full"
+          />
+        </UFormField>
+
+        <UFormField
+          :label="t('supabase.access.invite.roles')"
+          :error="showRolesError && roleKeys.length === 0 ? t('supabase.access.invite.rolesRequired') : undefined"
+          required
+        >
+          <UCheckboxGroup v-model="roleKeys" :items="roleItems" />
+        </UFormField>
+
+        <UFormField
+          :label="t('supabase.access.invite.locale')"
+          :description="t('supabase.access.invite.localeHint')"
+        >
+          <USelect v-model="emailLocale" :items="localeItems" class="w-full sm:w-64" />
+        </UFormField>
+
+        <!-- Enter in a field submits the form. -->
+        <button type="submit" class="hidden" tabindex="-1" aria-hidden="true" />
+      </form>
+    </template>
+
+    <template #footer>
+      <div class="flex w-full justify-end gap-2">
+        <template v-if="link">
+          <UButton @click="open = false">
+            {{ t('supabase.access.invite.done') }}
+          </UButton>
+        </template>
+
+        <template v-else>
+          <UButton color="neutral" variant="outline" @click="open = false">
+            {{ t('pluto.common.cancel') }}
+          </UButton>
+          <UButton :loading="submitting" icon="lucide:send" @click="submit">
+            {{ t('supabase.access.invite.submit') }}
+          </UButton>
+        </template>
+      </div>
+    </template>
+  </UModal>
+</template>

package/app/components/access/LinkField.vue

@@ -0,0 +1,19 @@
+<script setup lang="ts">
+// The invite link in a read-only field with a copy button, and the note: the
+// link works once and expires.
+defineProps<{
+  link: string
+}>()
+
+const { t } = usePlutoI18n()
+</script>
+
+<template>
+  <UFormField :label="t('supabase.access.link.label')" :help="t('supabase.access.link.note')">
+    <UInput :model-value="link" class="w-full" readonly @focus="($event.target as HTMLInputElement).select()">
+      <template #trailing>
+        <AccessCopyButton :text="link" :label="t('supabase.access.link.copy')" />
+      </template>
+    </UInput>
+  </UFormField>
+</template>