@plutocms/supabase 0.11.3 → 0.12.0

package/server/utils/access-mail.ts

@@ -0,0 +1,354 @@
+import type { H3Event } from 'h3'
+import type { serverSupabaseClient } from '#supabase/server'
+import type { ServiceClient } from './service-client'
+import { mapAccessError } from './access-errors'
+import { INVITE_ACCEPT_PATH } from './access-invite'
+import { emailInvalidError, isEmailInvalidError } from './sign-in-link'
+
+type UserClient = Awaited<ReturnType<typeof serverSupabaseClient<Database>>>
+
+/** The link types that the accept-invite page can verify. */
+export type AcceptLinkType = 'invite' | 'magiclink' | 'signup'
+
+const ACCEPT_LINK_TYPES: readonly string[] = ['invite', 'magiclink', 'signup']
+
+function inviteFailed() {
+  return createPlutoError({
+    statusCode: 502,
+    message: 'The invite email could not be sent.',
+    key: 'supabase.access.errors.inviteFailed',
+  })
+}
+
+/** Finds the id of the account with this email, or null. */
+export async function findUserIdByEmail(client: UserClient, email: string): Promise<string | null> {
+  const { data, error } = await client.rpc('find_user_id_by_email', { p_email: email })
+
+  if (error) {
+    throw mapAccessError(error)
+  }
+
+  return data ?? null
+}
+
+/** Adds roles to a user. It keeps the roles the user has. */
+export async function addRoles(client: UserClient, target: string, roleKeys: string[]): Promise<void> {
+  const { error } = await client.rpc('add_user_roles', { target, role_keys: roleKeys })
+
+  if (error) {
+    throw mapAccessError(error)
+  }
+}
+
+/**
+ * The URL that the user opens to accept an invite. The accept-invite page
+ * reads `token_hash` and `type`, then calls `verifyOtp`.
+ */
+export function acceptInviteUrl(origin: string, hashedToken: string, type: AcceptLinkType): string {
+  const url = new URL(INVITE_ACCEPT_PATH, origin)
+
+  url.searchParams.set('token_hash', hashedToken)
+  url.searchParams.set('type', type)
+
+  return url.href
+}
+
+interface GenerateLinkParams {
+  email: string
+  type: 'invite' | 'magiclink'
+  redirectTo: string
+  origin: string
+  displayName?: string
+}
+
+type GeneratedLink =
+  | { kind: 'link', userId: string, link: string }
+  | { kind: 'exists' }
+
+/**
+ * Makes a one-time link with the service role key. GoTrue sends no email and
+ * skips the email rate limit. An `invite` link creates the user when the
+ * email has no account.
+ *
+ * GoTrue says which type the link has (`verification_type`). The link uses
+ * that type when the accept-invite page knows it, else the asked type.
+ */
+export async function generateAcceptLink(
+  service: ServiceClient,
+  params: GenerateLinkParams
+): Promise<GeneratedLink> {
+  const options = { redirectTo: params.redirectTo }
+  const { data, error } = params.type === 'invite'
+    ? await service.auth.admin.generateLink({
+        type: 'invite',
+        email: params.email,
+        options: { ...options, data: params.displayName ? { display_name: params.displayName } : {} },
+      })
+    : await service.auth.admin.generateLink({
+        type: 'magiclink',
+        email: params.email,
+        options,
+      })
+
+  if (error) {
+    if (error.code === 'email_exists' || error.code === 'user_already_exists') {
+      return { kind: 'exists' }
+    }
+
+    if (isEmailInvalidError(error)) {
+      throw emailInvalidError()
+    }
+
+    console.error('invite: generateLink failed:', error.message)
+
+    throw inviteFailed()
+  }
+
+  const hashedToken = data?.properties?.hashed_token
+  const userId = data?.user?.id
+
+  if (!hashedToken || !userId) {
+    console.error('invite: generateLink returned no token')
+
+    throw inviteFailed()
+  }
+
+  const verification = String(data.properties.verification_type ?? '')
+  const type = ACCEPT_LINK_TYPES.includes(verification)
+    ? (verification as AcceptLinkType)
+    : params.type
+
+  return { kind: 'link', userId, link: acceptInviteUrl(params.origin, hashedToken, type) }
+}
+
+interface ProvisionParams {
+  client: UserClient
+  service: ServiceClient
+  email: string
+  roleKeys: string[]
+  displayName?: string
+  redirectTo: string
+  origin: string
+  /** Make a link for an email that has an account. Default: true. */
+  linkForExisting?: boolean
+}
+
+export interface ProvisionResult {
+  userId: string
+  /** Null when the account existed and `linkForExisting` is false. */
+  link: string | null
+  /** True when this call made the account. False when it had one. */
+  created: boolean
+}
+
+/** The error of a route that needs the service role key. */
+export function serviceKeyRequiredError() {
+  return createPlutoError({
+    statusCode: 503,
+    message: 'Set NUXT_SUPABASE_SECRET_KEY on the server to make invite links.',
+    key: 'supabase.access.errors.serviceKeyRequired',
+  })
+}
+
+/**
+ * Grants the roles and makes a sign-in link, with no email. It needs the
+ * service role key.
+ *
+ * - An email with an account (confirmed or not): the roles are added, and the
+ *   link is a `magiclink`. The account is never deleted.
+ * - A new email: the `invite` link creates the user, then the roles are set.
+ *   If the roles fail, the new user is deleted.
+ * - The account appears after the lookup (a race): the roles are added.
+ */
+export async function provisionAccess(params: ProvisionParams): Promise<ProvisionResult> {
+  const { client, service, email, roleKeys } = params
+  const link = (type: 'invite' | 'magiclink') =>
+    generateAcceptLink(service, { ...params, type })
+
+  async function forExisting(userId: string): Promise<ProvisionResult> {
+    await addRoles(client, userId, roleKeys)
+
+    if (params.linkForExisting === false) {
+      return { userId, link: null, created: false }
+    }
+
+    // A magic link signs in AS that account. A confirmed account has its own
+    // password and needs no link, so the admin never gets one: this keeps an
+    // admin from taking over a customer's or another admin's account. Only an
+    // account that never confirmed (a pending invite, or a sign-up with no
+    // confirmation) gets a link, because it cannot sign in without one.
+    const { data: found, error: lookupError } = await service.auth.admin.getUserById(userId)
+
+    if (lookupError || !found.user) {
+      console.error('invite: getUserById failed for an existing account')
+
+      throw inviteFailed()
+    }
+
+    if (found.user.email_confirmed_at) {
+      return { userId, link: null, created: false }
+    }
+
+    const made = await link('magiclink')
+
+    if (made.kind !== 'link') {
+      throw inviteFailed()
+    }
+
+    return { userId, link: made.link, created: false }
+  }
+
+  const existingId = await findUserIdByEmail(client, email)
+
+  if (existingId) {
+    return forExisting(existingId)
+  }
+
+  const made = await link('invite')
+
+  if (made.kind === 'exists') {
+    const racedId = await findUserIdByEmail(client, email)
+
+    if (!racedId) {
+      throw inviteFailed()
+    }
+
+    return forExisting(racedId)
+  }
+
+  // The lookup found no account, so this call made it. Only this new account
+  // may be deleted when the role write fails.
+  const { error: setError } = await client.rpc('set_user_roles', {
+    target: made.userId,
+    role_keys: roleKeys,
+  })
+
+  if (setError) {
+    const { error: undoError } = await service.auth.admin.deleteUser(made.userId)
+
+    if (undoError) {
+      console.error('invite: could not delete the new user:', undoError.message)
+    }
+
+    throw mapAccessError(setError)
+  }
+
+  return { userId: made.userId, link: made.link, created: true }
+}
+
+/** True when Pluto mail can send. A failed check counts as not ready. */
+export async function plutoMailReady(): Promise<boolean> {
+  try {
+    return (await getPlutoMailStatus()).configured === true
+  } catch {
+    return false
+  }
+}
+
+/** The site name for the email: the `website_title` setting, else the config name. */
+export async function inviteSiteName(client: UserClient): Promise<string> {
+  try {
+    const { data } = await client
+      .from('settings')
+      .select('setting_value')
+      .eq('setting_key', 'website_title')
+      .maybeSingle()
+    const title = data?.setting_value?.trim()
+
+    if (title) {
+      return title
+    }
+  } catch {
+    // The setting is not readable. Use the config name below.
+  }
+
+  return String(useRuntimeConfig().public.websiteName ?? 'Pluto')
+}
+
+/** The labels of the roles, in the order of the keys. A key with no label stays as it is. */
+async function roleLabels(client: UserClient, roleKeys: string[]): Promise<string[]> {
+  try {
+    const { data } = await client.rpc('list_roles')
+    const labels = new Map((data ?? []).map((role) => [role.key, role.label]))
+
+    return roleKeys.map((key) => labels.get(key) || key)
+  } catch {
+    return roleKeys
+  }
+}
+
+interface InviteMailParams {
+  client: UserClient
+  to: string
+  link: string
+  userId: string
+  roleKeys: string[]
+  inviterName?: string
+  locale?: string
+}
+
+/**
+ * Sends the invite email with Pluto mail. It returns false when the send
+ * fails. The caller keeps the user and the roles, and gives the link to the
+ * admin. The log holds the error code only: no recipient, link or key.
+ */
+export async function sendInviteMail(params: InviteMailParams): Promise<boolean> {
+  try {
+    const [siteName, roles] = await Promise.all([
+      inviteSiteName(params.client),
+      roleLabels(params.client, params.roleKeys),
+    ])
+    const email = await renderPlutoEmail(
+      'invite',
+      { url: params.link, inviterName: params.inviterName, roles },
+      { locale: params.locale, siteName }
+    )
+
+    await sendPlutoMail({
+      to: params.to,
+      ...email,
+      idempotencyKey: `invite/${params.userId}/${globalThis.crypto.randomUUID()}`,
+    })
+
+    return true
+  } catch (error) {
+    const code = (error as { code?: unknown } | null)?.code
+
+    console.error('invite: the Pluto mail send failed:', typeof code === 'string' ? code : 'unknown')
+
+    return false
+  }
+}
+
+/** The name of the admin who invites, for the email. Empty when unknown. */
+export function inviterNameOf(user: { user_metadata?: Record<string, unknown> | null }): string | undefined {
+  const meta = user.user_metadata ?? {}
+
+  for (const value of [meta.display_name, meta.full_name, meta.name]) {
+    if (typeof value === 'string' && value.trim() !== '') {
+      return value.trim()
+    }
+  }
+
+  return undefined
+}
+
+/**
+ * Checks the optional email language against the admin languages. Throws a
+ * 400 for a language the admin does not have.
+ */
+export function assertInviteLocale(event: H3Event, locale: string | undefined): void {
+  if (locale === undefined) {
+    return
+  }
+
+  const adminLocales = useRuntimeConfig(event).public.plutoI18n?.adminLocales ?? []
+
+  if (!adminLocales.includes(locale)) {
+    throw createPlutoError({
+      statusCode: 400,
+      message: 'This language is not supported.',
+      key: 'supabase.errors.localeUnsupported',
+    })
+  }
+}

package/server/utils/admin-guard.ts

@@ -22,15 +22,16 @@ import { serverSupabaseClient, serverSupabaseUser } from '#supabase/server'
  * so querying it directly has no migration dependency at all.
  *
  * The trade-off: a user granted the `admin` role only through
- * `user_roles` (see `permissions-storage/SKILL.md`'s "Granting a role by
+ * `user_roles` by hand (see `permissions-storage/SKILL.md`'s "Granting a role by
  * hand"), with `profiles.is_admin` left `false`, cannot pass this check —
  * only RLS and `has_capability()`-gated routes recognize a role-only
  * admin. That is an acceptable, narrow limitation: `user_roles` cannot
  * exist before `004` has been applied, so a role-only admin can only
  * exist on a site that has already applied every current migration, at
  * which point there is nothing left for that admin to need
- * `/admin/migrations` for. If a future migration ever needs applying by
- * a role-only admin, grant them `profiles.is_admin = true` too.
+ * `/admin/migrations` for. Migration 008 also closes the gap: `set_user_roles`
+ * and `add_user_roles` keep `profiles.is_admin` in step with the `admin`
+ * role. After a hand-made grant, set `profiles.is_admin = true` too.
  *
  * `serverSupabaseUser` (from `@nuxtjs/supabase`, backed by
  * `client.auth.getClaims()`) returns decoded JWT claims, not a Supabase

package/server/utils/admin-role-guard.ts

@@ -0,0 +1,44 @@
+import type { H3Event } from 'h3'
+import { serverSupabaseClient, serverSupabaseUser } from '#supabase/server'
+
+/**
+ * Guards a server route so only an admin can call it, through
+ * `public.is_admin()`. That function reads `profiles.is_admin` and the
+ * `admin` role, so it also accepts an admin who has the role only.
+ *
+ * Use it for the access API (migration 008). Keep `requireAdmin` for the
+ * migrations routes: it needs no migration at all.
+ *
+ * The rpc runs with the session of the caller, so `auth.uid()` is the caller.
+ * Throws a 401 with no user, or a 403 for a user who is not an admin.
+ * Returns the claims (the user id is `sub`).
+ */
+export async function requireAdminRole(event: H3Event) {
+  const user = await serverSupabaseUser(event)
+
+  if (!user) {
+    throw createPlutoError({
+      statusCode: 401,
+      message: 'You must be logged in.',
+      key: 'supabase.errors.notLoggedIn',
+    })
+  }
+
+  const client = await serverSupabaseClient<Database>(event)
+  const { data, error } = await client.rpc('is_admin')
+
+  if (error) {
+    // Logged, never returned: the 403 must not tell the caller why.
+    console.error('requireAdminRole: is_admin() failed:', error.message)
+  }
+
+  if (error || data !== true) {
+    throw createPlutoError({
+      statusCode: 403,
+      message: 'Your account is not an admin.',
+      key: 'supabase.errors.notAdmin',
+    })
+  }
+
+  return user
+}

package/server/utils/rate-limit.ts

@@ -0,0 +1,84 @@
+/**
+ * A small in-memory rate limiter. It keeps the hit times of each key in a
+ * sliding window. The state lives in one server process, so it is a brake
+ * for a single instance, not a global limit.
+ */
+
+export interface RateLimitOptions {
+  /** The number of hits allowed in the window. */
+  limit: number
+  /** The window length, in milliseconds. */
+  windowMs: number
+}
+
+export interface RateLimitResult {
+  ok: boolean
+  /** Seconds until the next hit is allowed. 0 when `ok`. */
+  retryAfter: number
+}
+
+export function createRateLimiter(
+  options: RateLimitOptions,
+  now: () => number = Date.now
+) {
+  const hits = new Map<string, number[]>()
+
+  return {
+    /** Counts one hit for the key. It does not count a refused hit. */
+    hit(key: string): RateLimitResult {
+      const time = now()
+      const recent = (hits.get(key) ?? []).filter(
+        (stamp) => time - stamp < options.windowMs
+      )
+
+      if (recent.length >= options.limit) {
+        hits.set(key, recent)
+
+        return {
+          ok: false,
+          retryAfter: Math.max(
+            1,
+            Math.ceil((recent[0]! + options.windowMs - time) / 1000)
+          ),
+        }
+      }
+
+      recent.push(time)
+      hits.set(key, recent)
+
+      // Drop the keys that have no recent hit, so the map does not grow.
+      if (hits.size > 1000) {
+        for (const [other, stamps] of hits) {
+          if (stamps.every((stamp) => time - stamp >= options.windowMs)) {
+            hits.delete(other)
+          }
+        }
+      }
+
+      return { ok: true, retryAfter: 0 }
+    },
+    reset() {
+      hits.clear()
+    },
+  }
+}
+
+/** 10 invites per 10 minutes for each caller. */
+const inviteLimiter = createRateLimiter({ limit: 10, windowMs: 10 * 60 * 1000 })
+
+/**
+ * Throws a 429 when the caller sent too many invites. `sub` is the user id
+ * of the caller (the JWT `sub` claim).
+ */
+export function enforceInviteRateLimit(sub: string) {
+  const result = inviteLimiter.hit(sub)
+
+  if (!result.ok) {
+    throw createPlutoError({
+      statusCode: 429,
+      message: 'Too many invites. Wait a few minutes and try again.',
+      key: 'supabase.access.errors.rateLimited',
+      data: { retryAfter: result.retryAfter },
+    })
+  }
+}

package/server/utils/service-client.ts

@@ -0,0 +1,18 @@
+import type { H3Event } from 'h3'
+import { serverSupabaseServiceRole } from '#supabase/server'
+
+/**
+ * Returns the Supabase client with the service role key, or null when the
+ * key is not set. The key is optional for invites: without it, the invite
+ * routes send a sign-in link instead (see `sign-in-link.ts`).
+ */
+export function optionalServiceClient(event: H3Event) {
+  try {
+    return serverSupabaseServiceRole<Database>(event)
+  } catch {
+    return null
+  }
+}
+
+/** The client of `optionalServiceClient`, when the key is set. */
+export type ServiceClient = NonNullable<ReturnType<typeof optionalServiceClient>>

package/server/utils/sign-in-link.ts

@@ -0,0 +1,129 @@
+import type { H3Event } from 'h3'
+import { createClient } from '@supabase/supabase-js'
+
+interface SignInLinkOptions {
+  redirectTo: string
+  displayName?: string
+  /** Create the account when the email has none. */
+  createUser: boolean
+}
+
+/**
+ * Sends a passwordless sign-in link with the anon key. The invite routes use
+ * it when the service role key is not set, so an invite needs no setup.
+ *
+ * - A new client per call, with no session storage, so the admin's own
+ *   session is never touched.
+ * - The implicit flow: the link comes back with the tokens in the URL hash.
+ *   The PKCE flow cannot work here, because its code verifier would stay in
+ *   this server-side client. The accept-invite page reads the hash.
+ * - With `createUser`, GoTrue creates the account (public sign-up must be
+ *   on). The trigger makes the profile from `display_name`.
+ */
+export async function sendSignInLink(
+  event: H3Event,
+  email: string,
+  options: SignInLinkOptions
+) {
+  const { url, key } = useRuntimeConfig(event).public.supabase
+  const client = createClient(url, key, {
+    auth: {
+      flowType: 'implicit',
+      persistSession: false,
+      autoRefreshToken: false,
+      detectSessionInUrl: false,
+    },
+  })
+
+  const { error } = await client.auth.signInWithOtp({
+    email,
+    options: {
+      shouldCreateUser: options.createUser,
+      emailRedirectTo: options.redirectTo,
+      data: options.displayName ? { display_name: options.displayName } : undefined,
+    },
+  })
+
+  return { error }
+}
+
+/**
+ * True when Supabase's built-in mailer refuses the address. Without custom
+ * SMTP, Supabase sends auth emails only to members of the project's
+ * organization.
+ */
+export function isEmailNotAuthorizedError(error: { code?: string } | null | undefined): boolean {
+  return error?.code === 'email_address_not_authorized'
+}
+
+export function emailNotAuthorizedError() {
+  return createPlutoError({
+    statusCode: 400,
+    message: 'Supabase\'s built-in email sends only to members of your Supabase organization. Set up custom SMTP in Supabase to invite other addresses.',
+    key: 'supabase.access.errors.emailNotAuthorized',
+  })
+}
+
+/**
+ * True when Supabase refuses to send more auth emails: one per address each
+ * 60 seconds, and a few per hour for the project with the built-in mailer.
+ * This is not the in-memory limit of `rate-limit.ts`.
+ */
+export function isEmailRateLimitError(error: { code?: string, status?: number } | null | undefined): boolean {
+  return error?.status === 429 || error?.code === 'over_email_send_rate_limit'
+}
+
+export function emailRateLimitError() {
+  return createPlutoError({
+    statusCode: 429,
+    message: 'Supabase sent too many emails. Wait a minute for the same address, or up to an hour with the built-in mailer. Custom SMTP in Supabase raises this limit.',
+    key: 'supabase.access.errors.emailRateLimited',
+  })
+}
+
+/**
+ * True when Supabase refuses the address itself, for example an example or
+ * test domain (`example.com`), or an address it cannot deliver to.
+ */
+export function isEmailInvalidError(error: { code?: string } | null | undefined): boolean {
+  return error?.code === 'email_address_invalid'
+}
+
+export function emailInvalidError() {
+  return createPlutoError({
+    statusCode: 400,
+    message: 'Supabase does not accept this email address. Use a real address: Supabase refuses example and test domains.',
+    key: 'supabase.access.errors.emailInvalid',
+  })
+}
+
+/** Maps a GoTrue error of `signInWithOtp` to a Pluto error. */
+export function signInLinkError(error: { code?: string, status?: number, message: string }) {
+  if (isEmailNotAuthorizedError(error)) {
+    return emailNotAuthorizedError()
+  }
+
+  if (isEmailInvalidError(error)) {
+    return emailInvalidError()
+  }
+
+  if (isEmailRateLimitError(error)) {
+    return emailRateLimitError()
+  }
+
+  if (error.code === 'signup_disabled' || error.code === 'otp_disabled') {
+    return createPlutoError({
+      statusCode: 503,
+      message: 'Public sign-up is off. Set NUXT_SUPABASE_SECRET_KEY on the server to send invites.',
+      key: 'supabase.access.errors.signupDisabled',
+    })
+  }
+
+  console.error('invite: signInWithOtp failed:', error.message)
+
+  return createPlutoError({
+    statusCode: 502,
+    message: 'The invite email could not be sent.',
+    key: 'supabase.access.errors.inviteFailed',
+  })
+}

package/shared/types/access.d.ts

@@ -0,0 +1,41 @@
+/** A staff user, as `GET /api/access/users` returns it (`list_staff_users`). */
+export interface AccessUser {
+  id: string
+  email: string | null
+  display_name: string | null
+  username: string | null
+  /** The `profiles.is_admin` flag. */
+  is_admin: boolean
+  /** The role keys of the user. */
+  roles: string[]
+  invited_at: string | null
+  /** Empty until the user accepts the invite. */
+  email_confirmed_at: string | null
+  last_sign_in_at: string | null
+}
+
+/** A role, as `GET /api/access/roles` returns it (`list_roles`). */
+export interface AccessRole {
+  key: string
+  label: string
+  description: string
+  is_builtin: boolean
+  capabilities: string[]
+  user_count: number
+}
+
+/** The answer of `GET /api/access/capabilities`. */
+export interface AccessCapabilities {
+  /** True when the service role key is set on the server. */
+  serviceKey: boolean
+  mail: { configured: boolean }
+}
+
+/** The answer of `POST /api/access/users/invite`. */
+export interface AccessInviteResult {
+  status: 'invited' | 'granted'
+  /** Present on the Pluto mail path. False when the send failed. */
+  emailSent?: boolean
+  /** Present when `emailSent` is false. */
+  link?: string
+}