Role Guard Usage Guide

// Determines app-wide privileges
type UserRole = 'member' | 'admin' | 'super_admin'

// Determines organization-specific privileges
type OrgRole = 'org:admin' | 'org:member'

type AnyRole = UserRole | OrgRole
// Can be: 'member' | 'admin' | 'super_admin' | 'org:admin' | 'org:member'

canViewContent(
  locals: App.Locals,
  allowedRoles: AnyRole[],
  options?: Partial<RoleGuardConfig>
): Promise<boolean>

canViewContentDetailed(
  locals: App.Locals,
  allowedRoles: AnyRole[],
  options?: Partial<RoleGuardConfig>
): Promise<RoleCheckResult>

requireRole(
  locals: App.Locals,
  allowedRoles: AnyRole[],
  options?: Partial<RoleGuardConfig>
): Promise<void>

getUserRole(locals: App.Locals, fetchFromSupabase?: boolean): Promise<AnyRole | null>

---
import { getUserRole } from '#utils/role-guard'

// Get org role from Clerk session (if available)
const orgRole = await getUserRole(Astro.locals, false)

// Get user role from Supabase (with fallback)
const userRole = await getUserRole(Astro.locals, true)

console.log('Org role:', orgRole) // e.g., 'org:admin' or null
console.log('User role:', userRole) // e.g., 'admin' or 'member'
---

hasAnyRole(locals: App.Locals, roles: AnyRole[]): Promise<boolean>
hasAllRoles(locals: App.Locals, roles: AnyRole[]): Promise<boolean>

const userInput = 'admin'

if (isValidRole(userInput)) {
  // TypeScript now knows userInput is AnyRole
  const label = ROLE_LABELS[userInput]
}

formatRoleForDisplay('super_admin') // Returns: "Super Admin"
formatRoleForDisplay('org:admin') // Returns: "Organization Admin"
formatRoleForDisplay('member') // Returns: "Member"

interface Props {
  allowedRoles: AnyRole[] // Required - roles that can view content
  fallback?: string // Optional - message when access denied
  debug?: boolean // Optional - show debug info (dev only)
  fetchFromSupabase?: boolean // Optional - query Supabase (default: true)
}

interface RoleGuardProps {
  userRole: AnyRole | null // Required - pre-fetched server-side
  allowedRoles: AnyRole[] // Required - roles that can view content
  children: ReactNode // Required - content to protect
  fallback?: ReactNode // Optional - shown when access denied
  loading?: boolean // Optional - show loading state
  className?: string // Optional - custom CSS class
  'data-testid'?: string // Optional - for testing
}

---
import { canViewContent } from '#utils/role-guard'

const canViewBasic = await canViewContent(Astro.locals, ['member', 'admin', 'super_admin'])
const canViewPremium = await canViewContent(Astro.locals, ['admin', 'super_admin'])
const canViewAdmin = await canViewContent(Astro.locals, ['super_admin'])
---

{
  canViewBasic && (
    <section>
      <h2>Basic Content</h2>
      <p>All authenticated users can see this</p>
    </section>
  )
}

{
  canViewPremium && (
    <section>
      <h2>Premium Content</h2>
      <p>Only admins and super admins can see this</p>
    </section>
  )
}

{
  canViewAdmin && (
    <section>
      <h2>Super Admin Content</h2>
      <p>Highest privilege only</p>
    </section>
  )
}

<RoleGuard
  allowedRoles={[
    'super_admin', // Supabase user role
    'org:admin', // Clerk org role
  ]}
>
  <AdvancedSettings />
</RoleGuard>

---
import { requireRole } from '#utils/role-guard'
import RoleGuard from '#components/astro/RoleGuard.astro'

// Page-level: Only admins can access page at all
await requireRole(Astro.locals, ['admin', 'super_admin'])
---

<html>
  <body>
    <h1>Admin Dashboard</h1>

    <!-- Component-level: Only super_admins see danger zone -->
    <RoleGuard allowedRoles={['super_admin']}>
      <DangerZone />
    </RoleGuard>
  </body>
</html>

---
import { canViewContent } from '#utils/role-guard'

const canViewAdmin = await canViewContent(Astro.locals, ['admin', 'super_admin'])
const canViewOrg = await canViewContent(Astro.locals, ['org:admin'])
---

<nav>
  <a href="/">Home</a>
  <a href="/dashboard">Dashboard</a>

  {canViewOrg && <a href="/organization">Organization</a>}
  {canViewAdmin && <a href="/admin">Admin</a>}
</nav>

function UserForm({ userRole }: Props) {
  return (
    <form>
      <input name="username" placeholder="Username" />
      <input name="email" type="email" placeholder="Email" />

      {/* Only admins can change roles */}
      <RoleGuard userRole={userRole} allowedRoles={['admin', 'super_admin']}>
        <select name="role">
          <option value="member">Member</option>
          <option value="admin">Admin</option>
        </select>
      </RoleGuard>
    </form>
  )
}

---
// Short TTL (30 seconds) for frequently changing roles
const canView = await canViewContent(Astro.locals, ['admin'], { cacheTTL: 30000 })

// Long TTL (5 minutes) for stable roles
const canView = await canViewContent(Astro.locals, ['admin'], { cacheTTL: 300000 })
---

---
// ✅ Fast - uses Astro.locals (org role)
const canManageOrg = await canViewContent(Astro.locals, ['org:admin'], {
  fetchFromSupabase: false,
})

// ⚠️ Slower - queries Supabase
const isAdmin = await canViewContent(Astro.locals, ['admin'], { fetchFromSupabase: true })
---

// src/middleware.ts (enhancement)
if (isProtectedRoute(context.request)) {
  locals.supabaseRole = await fetchSupabaseRole(locals.userId)
}

---
import { getUserRole } from '#utils/role-guard'

const userRole = await getUserRole(Astro.locals, true)

const features = [
  { name: 'Basic Feature', allowedRoles: ['member', 'admin', 'super_admin'] },
  { name: 'Admin Feature', allowedRoles: ['admin', 'super_admin'] },
  { name: 'Super Feature', allowedRoles: ['super_admin'] },
]
---

{
  features.map(
    feature =>
      userRole && feature.allowedRoles.includes(userRole) && <FeatureCard name={feature.name} />
  )
}

---
// WRONG - userRole not fetched
;<Dashboard client:load />

// RIGHT - fetch server-side and pass as prop
import { getUserRole } from '#utils/role-guard'
const userRole = await getUserRole(Astro.locals, true)
---

<Dashboard userRole={userRole} client:load />

// Monitor cache performance
import { getRoleCacheStats } from '#utils/role-guard'
const stats = getRoleCacheStats()
console.log('Cache entries:', stats.entries, 'Size:', stats.size)