spine-framework 0.3.54 → 0.3.56

package/.framework/functions/invites.ts

@@ -0,0 +1,655 @@
+/**
+ * @module invites
+ * @audience core-contributor
+ * @layer api-handler
+ * @stability stable
+ *
+ * Invite and access-request management. All invite/access-request state is
+ * stored directly on `people` rows — no separate table. Invite metadata lives
+ * in `people.data` under `invite_*` keys.
+ *
+ * **Routed by:** `GET/POST /.netlify/functions/invites?action=<action>`
+ *
+ * **Public actions (no auth required):**
+ * | action            | method | description |
+ * |-------------------|--------|-------------|
+ * | check-first-user  | GET    | Boolean: is this the first user registration? |
+ * | check-domain      | GET    | Boolean: does this email domain have existing accounts? |
+ * | validate-token    | GET    | Validate invite token, return preview |
+ * | complete-registration | POST | Finalise walk-up registration after Supabase auth |
+ *
+ * **Protected actions (require *_admin or system_admin):**
+ * | action         | method | description |
+ * |----------------|--------|-------------|
+ * | create-invite  | POST   | Create invite stub + return shareable URL |
+ * | list-invites   | GET    | List invites scoped to account (or all for system_admin) |
+ * | revoke-invite  | POST   | Mark invite inactive |
+ * | reinvite       | POST   | Issue new token on existing stub |
+ * | approve        | POST   | Approve access_request → activate person |
+ * | deny           | POST   | Deny access_request → deactivate person |
+ *
+ * **Invite metadata in people.data:**
+ * ```json
+ * {
+ *   "invite_token":       "abc123...",
+ *   "invite_kind":        "invite" | "access_request",
+ *   "invite_expires_at":  "2026-06-24T...",
+ *   "invite_attempts":    0,
+ *   "invite_blocked_at":  null,
+ *   "invite_invited_by":  "person-uuid"
+ * }
+ * ```
+ *
+ * **people.status values used here:**
+ *   invited  — unclaimed admin invite
+ *   pending  — walk-up access request awaiting approval
+ *   active   — approved / invite redeemed
+ *   inactive — denied / revoked
+ *
+ * @seeAlso migrations/016_invites.sql   (indexes)
+ * @seeAlso migrations/005_auth_user_trigger.sql  (stub resolution on signup)
+ * @seeAlso src/pages/auth/RegisterPage.tsx  (frontend)
+ * @seeAlso src/components/shared/InviteManager.tsx  (UI)
+ */
+
+import { createHandler } from './_shared/middleware'
+import { adminDb } from './_shared/db'
+import { emitLog } from './_shared/audit'
+
+// ─── CONSTANTS ────────────────────────────────────────────────────────────────
+
+const TOKEN_LENGTH = 16
+const MAX_ATTEMPTS = 5
+const INVITE_EXPIRY_DAYS = 7
+
+// Personal/free email domains — excluded from domain-match logic
+const PERSONAL_DOMAINS = new Set([
+  'gmail.com', 'yahoo.com', 'hotmail.com', 'outlook.com', 'icloud.com',
+  'aol.com', 'protonmail.com', 'me.com', 'mac.com', 'live.com',
+  'msn.com', 'ymail.com', 'googlemail.com', 'fastmail.com',
+])
+
+// ─── HELPERS ──────────────────────────────────────────────────────────────────
+
+function generateToken(): string {
+  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789'
+  const bytes = crypto.getRandomValues(new Uint8Array(TOKEN_LENGTH))
+  return Array.from(bytes).map(b => chars[b % chars.length]).join('')
+}
+
+function generateAccountSlug(name: string): string {
+  const base = name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40)
+  const hash = Math.random().toString(36).slice(2, 8)
+  return `${base}-${hash}`
+}
+
+function isAdminRole(roleSlug: string | undefined): boolean {
+  return !!roleSlug && (
+    roleSlug === 'system_admin' ||
+    roleSlug.endsWith('_admin')
+  )
+}
+
+// ─── PUBLIC: check-first-user ─────────────────────────────────────────────────
+
+/**
+ * Returns { is_first_user: boolean } — true if there are zero people in the system.
+ * Used by RegisterPage to show simplified first-user flow.
+ */
+export const checkFirstUser = createHandler(async (_ctx, _body) => {
+  const { count, error } = await adminDb
+    .from('people')
+    .select('*', { count: 'exact', head: true })
+
+  if (error) throw new Error('Failed to check first user: ' + error.message)
+
+  return { is_first_user: (count ?? 0) === 0 }
+})
+
+// ─── PUBLIC: check-domain ─────────────────────────────────────────────────────
+
+/**
+ * Returns { match: boolean } — whether any active people rows exist with the
+ * same email domain AND it's not a known personal domain.
+ * Does NOT return account names or IDs to avoid leaking structure.
+ */
+export const checkDomain = createHandler(async (_ctx, _body) => {
+  const email = _ctx.query?.email as string | undefined
+  if (!email || !email.includes('@')) {
+    throw new Error('Valid email is required')
+  }
+
+  const domain = email.split('@')[1].toLowerCase()
+
+  if (PERSONAL_DOMAINS.has(domain)) {
+    return { match: false }
+  }
+
+  const { data } = await adminDb
+    .from('people')
+    .select('id')
+    .ilike('email', `%@${domain}`)
+    .eq('status', 'active')
+    .limit(1)
+
+  return { match: (data?.length ?? 0) > 0 }
+})
+
+// ─── PUBLIC: validate-token ───────────────────────────────────────────────────
+
+/**
+ * Looks up a people row by invite_token. Returns a safe preview (no UUIDs).
+ * Increments invite_attempts; blocks the token after MAX_ATTEMPTS failures.
+ */
+export const validateToken = createHandler(async (_ctx, _body) => {
+  const token = _ctx.query?.token as string | undefined
+  if (!token) throw new Error('Token is required')
+
+  const { data: person } = await adminDb
+    .from('people')
+    .select('id, email, account_id, role_id, status, data, account:accounts(display_name), role:roles(slug, name)')
+    .filter('data->>invite_token', 'eq', token)
+    .in('status', ['invited', 'pending'])
+    .single()
+
+  if (!person) {
+    throw new Error('Invite not found or already used')
+  }
+
+  const meta = person.data || {}
+
+  // Check blocked
+  if (meta.invite_blocked_at) {
+    throw new Error('This invite link has been blocked. Please contact the administrator.')
+  }
+
+  // Check expiry
+  if (meta.invite_expires_at && new Date(meta.invite_expires_at) < new Date()) {
+    throw new Error('This invite link has expired. Please request a new one.')
+  }
+
+  // Increment attempts
+  const attempts = (meta.invite_attempts || 0) + 1
+  const blocked = attempts >= MAX_ATTEMPTS
+
+  await adminDb
+    .from('people')
+    .update({
+      data: {
+        ...meta,
+        invite_attempts: attempts,
+        invite_blocked_at: blocked ? new Date().toISOString() : null,
+      },
+      updated_at: new Date().toISOString(),
+    })
+    .eq('id', person.id)
+
+  if (blocked) {
+    throw new Error('Too many failed attempts. This invite has been blocked.')
+  }
+
+  const account = Array.isArray(person.account) ? person.account[0] : person.account
+  const role = Array.isArray(person.role) ? person.role[0] : person.role
+
+  return {
+    email: person.email,
+    account_name: account?.display_name ?? null,
+    role_name: role?.name ?? null,
+    kind: meta.invite_kind,
+  }
+})
+
+// ─── PUBLIC: complete-registration ───────────────────────────────────────────
+
+/**
+ * Called by RegisterPage after Supabase auth.signUp completes.
+ * Handles three walk-up paths:
+ *   new_account   — creates account + activates person as *_admin
+ *   join_request  — creates access_request stub (person stays pending)
+ *   (invite path is handled entirely in the DB trigger)
+ */
+export const completeRegistration = createHandler(async (ctx, body) => {
+  const { path, account_name, email } = body
+
+  if (!path || !email) {
+    throw new Error('path and email are required')
+  }
+
+  if (path === 'new_account') {
+    if (!account_name) throw new Error('account_name is required for new_account path')
+
+    // Resolve person type_id
+    const { data: personType } = await adminDb
+      .from('types')
+      .select('id, design_schema, validation_schema')
+      .eq('kind', 'person')
+      .eq('slug', 'person')
+      .single()
+
+    // Resolve account type_id
+    const { data: accountType } = await adminDb
+      .from('types')
+      .select('id')
+      .eq('kind', 'account')
+      .eq('slug', 'account')
+      .single()
+
+    // Resolve member_admin role (fall back to member if not seeded yet)
+    const { data: role } = await adminDb
+      .from('roles')
+      .select('id')
+      .in('slug', ['member_admin', 'member'])
+      .order('slug')   // member_admin sorts before member
+      .limit(1)
+      .single()
+
+    // Create account
+    const slug = generateAccountSlug(account_name)
+    const { data: account, error: accErr } = await adminDb
+      .from('accounts')
+      .insert({
+        slug,
+        display_name: account_name,
+        type_id: accountType?.id,
+        is_active: true,
+      })
+      .select('id')
+      .single()
+
+    if (accErr || !account) throw new Error('Failed to create account: ' + accErr?.message)
+
+    // Update the walk-up person shell (created by trigger as minimal record)
+    const { error: pErr } = await adminDb
+      .from('people')
+      .update({
+        account_id: account.id,
+        role_id: role?.id ?? null,
+        status: 'active',
+        updated_at: new Date().toISOString(),
+      })
+      .eq('email', email)
+      .eq('status', 'active')
+      .is('role_id', null)   // only the newly created shell
+
+    if (pErr) throw new Error('Failed to update person: ' + pErr.message)
+
+    return { status: 'active', account_slug: slug }
+  }
+
+  if (path === 'join_request') {
+    const { target_account_id } = body
+    if (!target_account_id) throw new Error('target_account_id is required for join_request')
+
+    // Resolve member role
+    const { data: role } = await adminDb
+      .from('roles')
+      .select('id')
+      .eq('slug', 'member')
+      .single()
+
+    // Resolve type_id
+    const { data: personType } = await adminDb
+      .from('types')
+      .select('id, design_schema, validation_schema')
+      .eq('kind', 'person')
+      .eq('slug', 'person')
+      .single()
+
+    // Update the walk-up shell to be a pending access request on the target account
+    const { error: pErr } = await adminDb
+      .from('people')
+      .update({
+        account_id: target_account_id,
+        role_id: role?.id ?? null,
+        status: 'pending',
+        data: {
+          invite_kind: 'access_request',
+          invite_invited_by: null,
+          invite_token: null,
+        },
+        updated_at: new Date().toISOString(),
+      })
+      .eq('email', email)
+      .eq('status', 'active')
+      .is('role_id', null)
+
+    if (pErr) throw new Error('Failed to create access request: ' + pErr.message)
+
+    return { status: 'pending' }
+  }
+
+  throw new Error('Unknown registration path: ' + path)
+})
+
+// ─── PROTECTED: create-invite ─────────────────────────────────────────────────
+
+/**
+ * Creates a stub people row (status: 'invited') with invite metadata.
+ * Returns the shareable token URL.
+ * Requires *_admin role scoped to the target account, or system_admin.
+ */
+export const createInvite = createHandler(async (ctx, body) => {
+  if (!ctx.principal || ctx.principal.id === 'anonymous') {
+    throw new Error('Authentication required')
+  }
+
+  const { email, account_id, role_id, base_url } = body
+  if (!email || !account_id || !role_id) {
+    throw new Error('email, account_id, and role_id are required')
+  }
+
+  // Verify caller is admin for this account
+  const { data: caller } = await adminDb
+    .from('people')
+    .select('role:roles(slug)')
+    .eq('id', ctx.principal.id)
+    .eq('account_id', account_id)
+    .single()
+
+  const callerRole = Array.isArray(caller?.role) ? caller?.role[0] : caller?.role
+  const callerRoleSlug = callerRole?.slug
+
+  const isSystemAdmin = ctx.principal.permissions?.includes('system') ||
+    callerRoleSlug === 'system_admin'
+  const isAccountAdmin = isAdminRole(callerRoleSlug)
+
+  if (!isSystemAdmin && !isAccountAdmin) {
+    throw new Error('Insufficient permissions — *_admin role required to create invites')
+  }
+
+  // Check for existing unclaimed invite for this email+account
+  const { data: existing } = await adminDb
+    .from('people')
+    .select('id')
+    .eq('email', email)
+    .eq('account_id', account_id)
+    .in('status', ['invited', 'active'])
+    .single()
+
+  if (existing) {
+    throw new Error('A person with this email already exists or has a pending invite for this account')
+  }
+
+  // Resolve type_id for person
+  const { data: personType } = await adminDb
+    .from('types')
+    .select('id, design_schema, validation_schema')
+    .eq('kind', 'person')
+    .eq('slug', 'person')
+    .single()
+
+  const token = generateToken()
+  const expiresAt = new Date(Date.now() + INVITE_EXPIRY_DAYS * 86400 * 1000).toISOString()
+
+  const { data: stub, error: insertErr } = await adminDb
+    .from('people')
+    .insert({
+      email,
+      full_name: email.split('@')[0],
+      account_id,
+      role_id,
+      type_id: personType?.id,
+      status: 'invited',
+      is_active: true,
+      design_schema: personType?.design_schema ?? {},
+      validation_schema: personType?.validation_schema ?? {},
+      data: {
+        invite_token: token,
+        invite_kind: 'invite',
+        invite_expires_at: expiresAt,
+        invite_attempts: 0,
+        invite_blocked_at: null,
+        invite_invited_by: ctx.principal.id,
+      },
+    })
+    .select('id')
+    .single()
+
+  if (insertErr || !stub) throw new Error('Failed to create invite: ' + insertErr?.message)
+
+  const appBaseUrl = base_url || process.env.APP_BASE_URL || 'https://yourapp.com'
+  const inviteUrl = `${appBaseUrl}/register?t=${token}`
+
+  await emitLog(ctx, 'invite.created', { type: 'person', id: stub.id }, {
+    after: { email, account_id, role_id, expires_at: expiresAt }
+  })
+
+  return { id: stub.id, token, invite_url: inviteUrl, expires_at: expiresAt }
+})
+
+// ─── PROTECTED: list-invites ──────────────────────────────────────────────────
+
+/**
+ * Lists people rows with invite metadata.
+ * system_admin sees all accounts; others see only their account.
+ */
+export const listInvites = createHandler(async (ctx, _body) => {
+  if (!ctx.principal || ctx.principal.id === 'anonymous') {
+    throw new Error('Authentication required')
+  }
+
+  const isSystemAdmin = ctx.principal.permissions?.includes('system')
+  const { account_id: queryAccountId } = ctx.query || {}
+
+  let query = adminDb
+    .from('people')
+    .select(`
+      id, email, full_name, status, created_at, updated_at,
+      account_id, role_id,
+      account:accounts(id, slug, display_name),
+      role:roles(id, slug, name),
+      data
+    `)
+    .not('data->>invite_kind', 'is', null)
+    .order('created_at', { ascending: false })
+
+  if (!isSystemAdmin) {
+    // Scoped to caller's account
+    const scopedAccountId = queryAccountId || ctx.accountId
+    if (!scopedAccountId) throw new Error('Account scope required')
+    query = query.eq('account_id', scopedAccountId)
+  } else if (queryAccountId) {
+    query = query.eq('account_id', queryAccountId)
+  }
+
+  const { data, error } = await query
+  if (error) throw error
+
+  return (data || []).map(row => ({
+    id: row.id,
+    email: row.email,
+    full_name: row.full_name,
+    status: row.status,
+    kind: (row.data as any)?.invite_kind,
+    expires_at: (row.data as any)?.invite_expires_at,
+    blocked_at: (row.data as any)?.invite_blocked_at,
+    created_at: row.created_at,
+    account: Array.isArray(row.account) ? row.account[0] : row.account,
+    role: Array.isArray(row.role) ? row.role[0] : row.role,
+  }))
+})
+
+// ─── PROTECTED: revoke-invite ─────────────────────────────────────────────────
+
+export const revokeInvite = createHandler(async (ctx, body) => {
+  if (!ctx.principal || ctx.principal.id === 'anonymous') throw new Error('Authentication required')
+
+  const { person_id } = body
+  if (!person_id) throw new Error('person_id is required')
+
+  const { data: person } = await adminDb
+    .from('people')
+    .select('id, account_id, status, data')
+    .eq('id', person_id)
+    .in('status', ['invited', 'pending'])
+    .single()
+
+  if (!person) throw new Error('Invite not found or already processed')
+
+  const { error } = await adminDb
+    .from('people')
+    .update({
+      status: 'inactive',
+      is_active: false,
+      data: { ...(person.data as any), invite_token: null },
+      updated_at: new Date().toISOString(),
+    })
+    .eq('id', person_id)
+
+  if (error) throw error
+
+  await emitLog(ctx, 'invite.revoked', { type: 'person', id: person_id }, {})
+
+  return { success: true }
+})
+
+// ─── PROTECTED: reinvite ──────────────────────────────────────────────────────
+
+export const reinvite = createHandler(async (ctx, body) => {
+  if (!ctx.principal || ctx.principal.id === 'anonymous') throw new Error('Authentication required')
+
+  const { person_id, base_url } = body
+  if (!person_id) throw new Error('person_id is required')
+
+  const { data: person } = await adminDb
+    .from('people')
+    .select('id, email, account_id, role_id, data, status')
+    .eq('id', person_id)
+    .single()
+
+  if (!person) throw new Error('Person not found')
+
+  const newToken = generateToken()
+  const expiresAt = new Date(Date.now() + INVITE_EXPIRY_DAYS * 86400 * 1000).toISOString()
+
+  const { error } = await adminDb
+    .from('people')
+    .update({
+      status: 'invited',
+      is_active: true,
+      data: {
+        ...(person.data as any),
+        invite_token: newToken,
+        invite_kind: 'invite',
+        invite_expires_at: expiresAt,
+        invite_attempts: 0,
+        invite_blocked_at: null,
+        invite_invited_by: ctx.principal.id,
+      },
+      updated_at: new Date().toISOString(),
+    })
+    .eq('id', person_id)
+
+  if (error) throw error
+
+  const appBaseUrl = base_url || process.env.APP_BASE_URL || 'https://yourapp.com'
+  const inviteUrl = `${appBaseUrl}/register?t=${newToken}`
+
+  await emitLog(ctx, 'invite.reinvited', { type: 'person', id: person_id }, {
+    after: { email: person.email, expires_at: expiresAt }
+  })
+
+  return { token: newToken, invite_url: inviteUrl, expires_at: expiresAt }
+})
+
+// ─── PROTECTED: approve ───────────────────────────────────────────────────────
+
+export const approve = createHandler(async (ctx, body) => {
+  if (!ctx.principal || ctx.principal.id === 'anonymous') throw new Error('Authentication required')
+
+  const { person_id } = body
+  if (!person_id) throw new Error('person_id is required')
+
+  const { data: person } = await adminDb
+    .from('people')
+    .select('id, email, account_id, data')
+    .eq('id', person_id)
+    .eq('status', 'pending')
+    .single()
+
+  if (!person) throw new Error('Access request not found or already processed')
+
+  // Strip invite metadata on approval
+  const { invite_token, invite_kind, invite_expires_at, invite_attempts, invite_blocked_at, invite_invited_by, ...remainingData } =
+    (person.data as any) || {}
+
+  const { error } = await adminDb
+    .from('people')
+    .update({
+      status: 'active',
+      is_active: true,
+      data: remainingData,
+      updated_at: new Date().toISOString(),
+    })
+    .eq('id', person_id)
+
+  if (error) throw error
+
+  await emitLog(ctx, 'invite.approved', { type: 'person', id: person_id }, {
+    after: { email: person.email, approved_by: ctx.principal.id }
+  })
+
+  return { success: true }
+})
+
+// ─── PROTECTED: deny ──────────────────────────────────────────────────────────
+
+export const deny = createHandler(async (ctx, body) => {
+  if (!ctx.principal || ctx.principal.id === 'anonymous') throw new Error('Authentication required')
+
+  const { person_id } = body
+  if (!person_id) throw new Error('person_id is required')
+
+  const { data: person } = await adminDb
+    .from('people')
+    .select('id, email, account_id, data')
+    .eq('id', person_id)
+    .eq('status', 'pending')
+    .single()
+
+  if (!person) throw new Error('Access request not found or already processed')
+
+  const { error } = await adminDb
+    .from('people')
+    .update({
+      status: 'inactive',
+      is_active: false,
+      updated_at: new Date().toISOString(),
+    })
+    .eq('id', person_id)
+
+  if (error) throw error
+
+  await emitLog(ctx, 'invite.denied', { type: 'person', id: person_id }, {
+    after: { email: person.email, denied_by: ctx.principal.id }
+  })
+
+  return { success: true }
+})
+
+// ─── MAIN HANDLER ────────────────────────────────────────────────────────────
+
+export const handler = createHandler(async (ctx, body) => {
+  const action = ctx.query?.action
+
+  switch (action) {
+    // Public
+    case 'check-first-user':    return await checkFirstUser(ctx, body)
+    case 'check-domain':        return await checkDomain(ctx, body)
+    case 'validate-token':      return await validateToken(ctx, body)
+    case 'complete-registration': return await completeRegistration(ctx, body)
+    // Protected
+    case 'create-invite':       return await createInvite(ctx, body)
+    case 'list-invites':        return await listInvites(ctx, body)
+    case 'revoke-invite':       return await revokeInvite(ctx, body)
+    case 'reinvite':            return await reinvite(ctx, body)
+    case 'approve':             return await approve(ctx, body)
+    case 'deny':                return await deny(ctx, body)
+    default:
+      throw new Error(`Unknown action: ${action}`)
+  }
+})