@plutocms/supabase 0.11.3 → 0.12.0

package/server/api/access/users/[id]/resend.post.ts

@@ -0,0 +1,172 @@
+import { serverSupabaseClient } from '#supabase/server'
+import { mapAccessError } from '../../../../utils/access-errors'
+import { inviteRedirectUrl, isEmailExistsError, requireUserId, resendBodySchema } from '../../../../utils/access-invite'
+import {
+  assertInviteLocale,
+  generateAcceptLink,
+  inviterNameOf,
+  plutoMailReady,
+  sendInviteMail,
+} from '../../../../utils/access-mail'
+import { requireAdminRole } from '../../../../utils/admin-role-guard'
+import { enforceInviteRateLimit } from '../../../../utils/rate-limit'
+import { optionalServiceClient } from '../../../../utils/service-client'
+import {
+  emailInvalidError,
+  emailNotAuthorizedError,
+  emailRateLimitError,
+  isEmailInvalidError,
+  isEmailNotAuthorizedError,
+  isEmailRateLimitError,
+  sendSignInLink,
+  signInLinkError,
+} from '../../../../utils/sign-in-link'
+import { parseBody } from '../../../../utils/validate'
+
+function notFound() {
+  return createPlutoError({
+    statusCode: 404,
+    message: 'This user does not exist.',
+    key: 'supabase.access.errors.userNotFound',
+  })
+}
+
+function alreadyAccepted() {
+  return createPlutoError({
+    statusCode: 409,
+    message: 'This user already accepted the invite.',
+    key: 'supabase.access.errors.alreadyAccepted',
+  })
+}
+
+/**
+ * Sends the invite email again. It works only for a user who has not
+ * accepted the invite yet (`email_confirmed_at` is empty).
+ *
+ * With the service role key and Pluto mail set up, GoTrue makes a one-time
+ * link and Pluto mail sends the email. If the send fails, the answer holds
+ * the link (`emailSent: false`). With the key and no Pluto mail, GoTrue
+ * sends the invite email. Without the key it
+ * reads the user from `list_staff_users` (an invited user has a role) and
+ * sends a sign-in link that never creates an account.
+ */
+export default defineEventHandler(async (event) => {
+  const caller = await requireAdminRole(event)
+
+  enforceInviteRateLimit(caller.sub)
+
+  const id = requireUserId(event.context.params?.id)
+  const locale = (await parseBody(event, resendBodySchema))?.locale
+
+  assertInviteLocale(event, locale)
+
+  const { origin } = getRequestURL(event)
+  const redirectTo = inviteRedirectUrl(origin)
+  const service = optionalServiceClient(event)
+
+  if (!service) {
+    const client = await serverSupabaseClient<Database>(event)
+    const { data: staff, error } = await client.rpc('list_staff_users')
+
+    if (error) {
+      throw mapAccessError(error)
+    }
+
+    const target = staff?.find((row) => row.id === id)
+
+    if (!target?.email) {
+      throw notFound()
+    }
+
+    if (target.email_confirmed_at) {
+      throw alreadyAccepted()
+    }
+
+    const { error: linkError } = await sendSignInLink(event, target.email, {
+      redirectTo,
+      createUser: false,
+    })
+
+    if (linkError) {
+      throw signInLinkError(linkError)
+    }
+
+    return { status: 'sent' as const }
+  }
+
+  const { data, error } = await service.auth.admin.getUserById(id)
+
+  if (error || !data.user) {
+    throw notFound()
+  }
+
+  const { email, email_confirmed_at: confirmedAt } = data.user
+
+  if (confirmedAt || !email) {
+    throw alreadyAccepted()
+  }
+
+  if (await plutoMailReady()) {
+    const client = await serverSupabaseClient<Database>(event)
+    const made = await generateAcceptLink(service, {
+      email,
+      type: 'invite',
+      redirectTo,
+      origin,
+    })
+
+    // A pending user cannot be "already registered" for an invite. It means
+    // the user accepted the invite in the meantime.
+    if (made.kind !== 'link') {
+      throw alreadyAccepted()
+    }
+
+    const { data: staff } = await client.rpc('list_staff_users')
+    const roleKeys = Array.isArray(staff) ? (staff.find((row) => row.id === id)?.roles ?? []) : []
+    const sent = await sendInviteMail({
+      client,
+      to: email,
+      link: made.link,
+      userId: id,
+      roleKeys,
+      inviterName: inviterNameOf(caller),
+      locale,
+    })
+
+    return sent
+      ? { status: 'sent' as const, emailSent: true }
+      : { status: 'sent' as const, emailSent: false, link: made.link }
+  }
+
+  const { error: inviteError } = await service.auth.admin.inviteUserByEmail(email, {
+    redirectTo,
+  })
+
+  if (inviteError) {
+    if (isEmailExistsError(inviteError)) {
+      throw alreadyAccepted()
+    }
+
+    if (isEmailNotAuthorizedError(inviteError)) {
+      throw emailNotAuthorizedError()
+    }
+
+    if (isEmailRateLimitError(inviteError)) {
+      throw emailRateLimitError()
+    }
+
+    if (isEmailInvalidError(inviteError)) {
+      throw emailInvalidError()
+    }
+
+    console.error('resend: inviteUserByEmail failed:', inviteError.message)
+
+    throw createPlutoError({
+      statusCode: 502,
+      message: 'The invite email could not be sent.',
+      key: 'supabase.access.errors.inviteFailed',
+    })
+  }
+
+  return { status: 'sent' as const }
+})

package/server/api/access/users/[id]/roles.delete.ts

@@ -0,0 +1,22 @@
+import { serverSupabaseClient } from '#supabase/server'
+import { mapAccessError } from '../../../../utils/access-errors'
+import { requireUserId } from '../../../../utils/access-invite'
+import { requireAdminRole } from '../../../../utils/admin-role-guard'
+
+/** Revokes the access of a user: it removes every role. The account stays. */
+export default defineEventHandler(async (event) => {
+  await requireAdminRole(event)
+
+  const id = requireUserId(event.context.params?.id)
+  const client = await serverSupabaseClient<Database>(event)
+  const { error } = await client.rpc('set_user_roles', {
+    target: id,
+    role_keys: [],
+  })
+
+  if (error) {
+    throw mapAccessError(error)
+  }
+
+  return { id }
+})

package/server/api/access/users/[id]/roles.put.ts

@@ -0,0 +1,24 @@
+import { serverSupabaseClient } from '#supabase/server'
+import { mapAccessError } from '../../../../utils/access-errors'
+import { requireUserId, rolesBodySchema } from '../../../../utils/access-invite'
+import { requireAdminRole } from '../../../../utils/admin-role-guard'
+import { parseBody } from '../../../../utils/validate'
+
+/** Replaces the roles of a user. An empty list revokes the access. */
+export default defineEventHandler(async (event) => {
+  await requireAdminRole(event)
+
+  const id = requireUserId(event.context.params?.id)
+  const { roleKeys } = await parseBody(event, rolesBodySchema)
+  const client = await serverSupabaseClient<Database>(event)
+  const { error } = await client.rpc('set_user_roles', {
+    target: id,
+    role_keys: roleKeys,
+  })
+
+  if (error) {
+    throw mapAccessError(error)
+  }
+
+  return { id }
+})

package/server/api/access/users/invite-link.post.ts

@@ -0,0 +1,50 @@
+import { serverSupabaseClient } from '#supabase/server'
+import { inviteBodySchema, inviteRedirectUrl } from '../../../utils/access-invite'
+import { provisionAccess, serviceKeyRequiredError } from '../../../utils/access-mail'
+import { requireAdminRole } from '../../../utils/admin-role-guard'
+import { enforceInviteRateLimit } from '../../../utils/rate-limit'
+import { optionalServiceClient } from '../../../utils/service-client'
+import { parseBody } from '../../../utils/validate'
+
+/**
+ * Grants the roles and returns a one-time sign-in link. No email is sent, so
+ * the Supabase mailer and its limits are not used. The admin copies the link
+ * and sends it to the user.
+ *
+ * It needs the service role key (`auth.admin.generateLink`). Without it, the
+ * answer is 503. The link expires, and it works once.
+ *
+ * - An email with an account: the roles are added, and the link is a
+ *   magic link for that account.
+ * - A new email: the invite link makes the user, then the roles are set.
+ *   If the roles fail, the new user is deleted.
+ */
+export default defineEventHandler(async (event) => {
+  const caller = await requireAdminRole(event)
+
+  enforceInviteRateLimit(caller.sub)
+
+  const { email, roleKeys, displayName } = await parseBody(event, inviteBodySchema)
+  const service = optionalServiceClient(event)
+
+  if (!service) {
+    throw serviceKeyRequiredError()
+  }
+
+  const client = await serverSupabaseClient<Database>(event)
+  const { origin } = getRequestURL(event)
+  const result = await provisionAccess({
+    client,
+    service,
+    email,
+    roleKeys,
+    displayName,
+    redirectTo: inviteRedirectUrl(origin),
+    origin,
+  })
+
+  return {
+    status: result.created ? ('invited' as const) : ('granted' as const),
+    link: result.link,
+  }
+})

package/server/api/access/users/invite.post.ts

@@ -0,0 +1,201 @@
+import { serverSupabaseClient } from '#supabase/server'
+import { mapAccessError } from '../../../utils/access-errors'
+import {
+  inviteBodySchema,
+  inviteRedirectUrl,
+  isEmailExistsError,
+} from '../../../utils/access-invite'
+import {
+  addRoles,
+  assertInviteLocale,
+  findUserIdByEmail,
+  inviterNameOf,
+  plutoMailReady,
+  provisionAccess,
+  sendInviteMail,
+} from '../../../utils/access-mail'
+import { requireAdminRole } from '../../../utils/admin-role-guard'
+import { enforceInviteRateLimit } from '../../../utils/rate-limit'
+import { optionalServiceClient } from '../../../utils/service-client'
+import {
+  emailInvalidError,
+  emailNotAuthorizedError,
+  emailRateLimitError,
+  isEmailInvalidError,
+  isEmailNotAuthorizedError,
+  isEmailRateLimitError,
+  sendSignInLink,
+  signInLinkError,
+} from '../../../utils/sign-in-link'
+import { parseBody } from '../../../utils/validate'
+
+/**
+ * Invites a user by email and grants the roles.
+ *
+ * - An email that has an account (confirmed or not): the roles are added.
+ *   No email is sent. The account is never deleted.
+ * - A new email, with the service role key and Pluto mail set up: GoTrue
+ *   makes the user and a one-time link (no email). The roles are set at
+ *   once. Pluto mail sends the invite email. If the send fails, the user
+ *   and the roles stay, and the answer holds the link (`emailSent: false`).
+ * - A new email, with the service role key and no Pluto mail: GoTrue creates
+ *   the user and sends the invite email. The roles are set at once. If the roles fail,
+ *   the new user is deleted.
+ * - A new email, without the key: a sign-in link with the anon key creates
+ *   the user and sends the email (the sign-up or magic link template). The
+ *   roles are set at once. If the roles fail, the account stays with no
+ *   role (the same as a sign-up), because only the key can delete a user.
+ *
+ * The role writes use the session of the caller (`auth.uid()` is the
+ * admin). Only the invite call uses the service role key.
+ */
+export default defineEventHandler(async (event) => {
+  const caller = await requireAdminRole(event)
+
+  enforceInviteRateLimit(caller.sub)
+
+  const { email, roleKeys, displayName, locale } = await parseBody(event, inviteBodySchema)
+
+  assertInviteLocale(event, locale)
+
+  const service = optionalServiceClient(event)
+  const client = await serverSupabaseClient<Database>(event)
+  const { origin } = getRequestURL(event)
+  const redirectTo = inviteRedirectUrl(origin)
+
+  // The key and a working mail driver: Pluto sends the email, not Supabase.
+  if (service && (await plutoMailReady())) {
+    const result = await provisionAccess({
+      client,
+      service,
+      email,
+      roleKeys,
+      displayName,
+      redirectTo,
+      origin,
+      linkForExisting: false,
+    })
+
+    // An account that exists only gets the roles, and no email.
+    if (!result.created || !result.link) {
+      return { status: 'granted' as const }
+    }
+
+    const sent = await sendInviteMail({
+      client,
+      to: email,
+      link: result.link,
+      userId: result.userId,
+      roleKeys,
+      inviterName: inviterNameOf(caller),
+      locale,
+    })
+
+    return sent
+      ? { status: 'invited' as const, emailSent: true }
+      : { status: 'invited' as const, emailSent: false, link: result.link }
+  }
+
+  // Look the email up first. An account that exists (confirmed or not) gets
+  // the roles added, and no email. The undo below must never delete it: an
+  // unconfirmed account can be a customer who did not confirm yet.
+  const existingId = await findUserIdByEmail(client, email)
+
+  if (existingId) {
+    await addRoles(client, existingId, roleKeys)
+    return { status: 'granted' as const }
+  }
+
+  if (!service) {
+    const { error: linkError } = await sendSignInLink(event, email, {
+      redirectTo,
+      displayName,
+      createUser: true,
+    })
+
+    if (linkError) {
+      throw signInLinkError(linkError)
+    }
+
+    const linkedId = await findUserIdByEmail(client, email)
+
+    if (!linkedId) {
+      console.error('invite: the sign-in link was sent, but no account has this email')
+
+      throw createPlutoError({
+        statusCode: 502,
+        message: 'The invite email could not be sent.',
+        key: 'supabase.access.errors.inviteFailed',
+      })
+    }
+
+    // An account can appear between the lookup and the link (a race). Adding
+    // keeps its roles; for a new account it is the same as setting them.
+    await addRoles(client, linkedId, roleKeys)
+    return { status: 'invited' as const }
+  }
+
+  const { data, error } = await service.auth.admin.inviteUserByEmail(email, {
+    redirectTo,
+    data: displayName ? { display_name: displayName } : {},
+  })
+
+  if (error) {
+    if (isEmailNotAuthorizedError(error)) {
+      throw emailNotAuthorizedError()
+    }
+
+    if (isEmailRateLimitError(error)) {
+      throw emailRateLimitError()
+    }
+
+    if (isEmailInvalidError(error)) {
+      throw emailInvalidError()
+    }
+
+    if (!isEmailExistsError(error)) {
+      console.error('invite: inviteUserByEmail failed:', error.message)
+
+      throw createPlutoError({
+        statusCode: 502,
+        message: 'The invite email could not be sent.',
+        key: 'supabase.access.errors.inviteFailed',
+      })
+    }
+
+    // The account appeared after the lookup above (a race). Add the roles.
+    const racedId = await findUserIdByEmail(client, email)
+
+    if (!racedId) {
+      throw createPlutoError({
+        statusCode: 502,
+        message: 'The invite email could not be sent.',
+        key: 'supabase.access.errors.inviteFailed',
+      })
+    }
+
+    await addRoles(client, racedId, roleKeys)
+    return { status: 'granted' as const }
+  }
+
+  // The lookup found no account, so GoTrue created this one now. Only this
+  // new account may be deleted when the role write fails.
+  const newId = data.user.id
+  const { error: setError } = await client.rpc('set_user_roles', {
+    target: newId,
+    role_keys: roleKeys,
+  })
+
+  if (setError) {
+    // Undo the invite, so a failed role write leaves no staff-less account.
+    const { error: undoError } = await service.auth.admin.deleteUser(newId)
+
+    if (undoError) {
+      console.error('invite: could not delete the new user:', undoError.message)
+    }
+
+    throw mapAccessError(setError)
+  }
+
+  return { status: 'invited' as const }
+})

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

@@ -0,0 +1,17 @@
+import { serverSupabaseClient } from '#supabase/server'
+import { mapAccessError } from '../../utils/access-errors'
+import { requireCapability } from '../../utils/capability-guard'
+
+/** The staff: users with a role, or with the admin flag. */
+export default defineEventHandler(async (event) => {
+  await requireCapability(event, 'users:read')
+
+  const client = await serverSupabaseClient<Database>(event)
+  const { data, error } = await client.rpc('list_staff_users')
+
+  if (error) {
+    throw mapAccessError(error)
+  }
+
+  return { users: data ?? [] }
+})

package/server/utils/access-errors.ts

@@ -0,0 +1,148 @@
+/**
+ * Maps the errors of the access functions (migration 008) to Pluto errors.
+ *
+ * A rule error from the database is `P0001` with the message
+ * `pluto:<code>`. A missing right is `42501` with `pluto:forbidden`.
+ * `createPlutoError` is a Nitro auto-import.
+ */
+
+interface AccessErrorDefinition {
+  statusCode: number
+  /** English text. It becomes the `statusMessage`. */
+  message: string
+  /** The translation key of the same message. */
+  key: string
+}
+
+/** The known rule codes, with the HTTP status and the English text. */
+export const ACCESS_ERRORS = {
+  forbidden: {
+    statusCode: 403,
+    message: 'Only an admin can do this.',
+    key: 'supabase.access.errors.forbidden',
+  },
+  last_admin: {
+    statusCode: 409,
+    message: 'This is the last admin. Make another user an admin first.',
+    key: 'supabase.access.errors.lastAdmin',
+  },
+  role_exists: {
+    statusCode: 409,
+    message: 'A role with this key already exists.',
+    key: 'supabase.access.errors.roleExists',
+  },
+  builtin_role: {
+    statusCode: 400,
+    message: 'A built-in role cannot be changed or deleted.',
+    key: 'supabase.access.errors.builtinRole',
+  },
+  wildcard: {
+    statusCode: 400,
+    message: 'A new role cannot hold the wildcard permission.',
+    key: 'supabase.access.errors.wildcard',
+  },
+  empty_role: {
+    statusCode: 400,
+    message: 'A role needs at least one permission.',
+    key: 'supabase.access.errors.emptyRole',
+  },
+  unknown_role: {
+    statusCode: 400,
+    message: 'One of the roles does not exist.',
+    key: 'supabase.access.errors.unknownRole',
+  },
+  invalid_key: {
+    statusCode: 400,
+    message: 'The role key can use only a-z, 0-9 and an underscore.',
+    key: 'supabase.access.errors.invalidKey',
+  },
+  invalid_label: {
+    statusCode: 400,
+    message: 'The role needs a name.',
+    key: 'supabase.access.errors.invalidLabel',
+  },
+  invalid_capability: {
+    statusCode: 400,
+    message: 'One of the permissions is not valid.',
+    key: 'supabase.access.errors.invalidCapability',
+  },
+  user_not_found: {
+    statusCode: 404,
+    message: 'This user does not exist.',
+    key: 'supabase.access.errors.userNotFound',
+  },
+  role_not_found: {
+    statusCode: 404,
+    message: 'This role does not exist.',
+    key: 'supabase.access.errors.roleNotFound',
+  },
+} as const satisfies Record<string, AccessErrorDefinition>
+
+export type AccessErrorCode = keyof typeof ACCESS_ERRORS
+
+interface PgErrorLike {
+  code?: string
+  message?: string
+}
+
+/**
+ * Reads the rule code of a database error. It returns undefined when the
+ * error is not a rule error of the access functions.
+ */
+export function parseAccessCode(
+  error: PgErrorLike | null | undefined
+): AccessErrorCode | undefined {
+  const code = error?.message?.match(/^pluto:([a-z_]+)$/)?.[1]
+
+  if (code && code in ACCESS_ERRORS) {
+    return code as AccessErrorCode
+  }
+
+  // Postgres refuses the call by itself, for example a missing grant.
+  if (error?.code === '42501') {
+    return 'forbidden'
+  }
+
+  return undefined
+}
+
+/** True when the database has no access function yet (008 is pending). */
+export function isMissingAccessFunction(error: PgErrorLike | null | undefined) {
+  return (
+    error?.code === 'PGRST202' ||
+    error?.code === '42883' ||
+    /could not find the function/i.test(error?.message ?? '')
+  )
+}
+
+/**
+ * Builds the error to throw for a failed access call. A known rule code gets
+ * its status and its `supabase.access.errors.<code>` key. A pending 008
+ * migration gets 409. Any other error is a plain 500.
+ */
+export function mapAccessError(error: PgErrorLike) {
+  const code = parseAccessCode(error)
+
+  if (code) {
+    const { statusCode, message, key } = ACCESS_ERRORS[code]
+
+    return createPlutoError({
+      statusCode,
+      message,
+      key,
+    })
+  }
+
+  if (isMissingAccessFunction(error)) {
+    return createPlutoError({
+      statusCode: 409,
+      message: 'Apply the pending database migrations to manage users and roles.',
+      key: 'supabase.access.errors.migrationPending',
+    })
+  }
+
+  return createError({
+    statusCode: 500,
+    statusMessage: error.message || 'Unknown error.',
+  })
+}

package/server/utils/access-invite.ts

@@ -0,0 +1,66 @@
+import { z } from 'zod'
+
+/** The page where an invited user sets a password. */
+export const INVITE_ACCEPT_PATH = '/admin/accept-invite'
+
+/** Role and capability keys: lower-case letters, digits and an underscore. */
+export const ROLE_KEY_PATTERN = /^[a-z0-9_]+$/
+
+export const inviteBodySchema = z.object({
+  email: z.string().trim().toLowerCase().pipe(z.email()),
+  roleKeys: z.array(z.string().regex(ROLE_KEY_PATTERN)).min(1).max(20),
+  displayName: z.string().trim().max(200).optional(),
+  /** The language of the invite email. Checked against the admin languages. */
+  locale: z.string().trim().min(1).max(35).optional(),
+})
+
+/** The body of the resend route. It is optional. */
+export const resendBodySchema = z
+  .object({
+    locale: z.string().trim().min(1).max(35).optional(),
+  })
+  .nullish()
+
+export const rolesBodySchema = z.object({
+  roleKeys: z.array(z.string().regex(ROLE_KEY_PATTERN)).max(20),
+})
+
+export const roleBodySchema = z.object({
+  label: z.string().trim().min(1).max(100),
+  description: z.string().trim().max(500).optional(),
+  capabilities: z
+    .array(z.string().regex(/^[a-z0-9_]+:[a-z0-9_]+$/))
+    .min(1)
+    .max(200),
+})
+
+export const createRoleBodySchema = roleBodySchema.extend({
+  key: z.string().regex(ROLE_KEY_PATTERN).max(50),
+})
+
+/** The link target of the invite email, on the origin of this request. */
+export function inviteRedirectUrl(origin: string): string {
+  return new URL(INVITE_ACCEPT_PATH, origin).href
+}
+
+/** True when GoTrue says that an account with this email already exists. */
+export function isEmailExistsError(
+  error: { code?: string, status?: number } | null | undefined
+): boolean {
+  return error?.code === 'email_exists' || error?.code === 'user_already_exists'
+}
+
+/** Reads a user id from a route param. Throws a 400 when it is not a UUID. */
+export function requireUserId(value: unknown): string {
+  const parsed = z.uuid().safeParse(value)
+
+  if (!parsed.success) {
+    throw createPlutoError({
+      statusCode: 400,
+      message: 'The user id is not valid.',
+      key: 'supabase.access.errors.invalidUserId',
+    })
+  }
+
+  return parsed.data
+}