Role Guard Usage Guide

The role-based visibility system provides a unified API for controlling content access based on user roles. Supports both Supabase user roles (app-level) and Clerk organization roles (org-level) through a single, consistent interface.

Version: 1.0 | Status: ✅ Production Ready

Looking for page-level protection? See the dedicated Page-Level Protection Guide for complete coverage of requireRole() with hierarchical privilege escalation.

Looking for declarative page protection? See the Auth Layout Role Guards Guide for protecting entire pages using Auth layout props instead of manual role checks.

Overview

The role guard system provides:

• Unified API for Supabase and Clerk roles
• Server-side security with zero client JavaScript
• Automatic caching with configurable TTL (default: 1 minute)
• Type safety with full TypeScript support
• Flexible usage - utilities and components
• Well-tested - 54+ unit and component tests

🛡️ Utility Functions

Use canViewContent(), requireRole(), and getUserRole() for programmatic role checks with detailed results.

🎨 Wrapper Components

Use <RoleGuard> components in Astro and React to hide/show content based on user roles with zero configuration.

⚡ Performance

Built-in caching with 1-minute TTL reduces database queries. Configure cache duration per check.

🔍 Debug Mode

Development-only debug mode shows role checking details to help troubleshoot access issues.

Quick Start

30-Second Example

src/pages/admin.astro

---
import RoleGuard from '#components/astro/RoleGuard.astro'
---

<RoleGuard allowedRoles={['admin', 'super_admin']}>
  <h1>Admin Dashboard</h1>
  <p>Only admins can see this content</p>
</RoleGuard>

That’s it! The component handles everything:

• ✅ Fetches user role from Astro.locals or Supabase
• ✅ Checks if user has any allowed role
• ✅ Hides content if unauthorized
• ✅ Caches role queries (1-minute TTL)

Core Concepts

Two Role Systems

The astro-basics project uses two independent role systems:

1. Supabase User Roles (App-Level)

Storage: Supabase users table Sync Source: Clerk webhook → Supabase Roles: member, admin, super_admin

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

Use Cases:

• Global admin features
• User management
• System configuration
• Cross-organization permissions

2. Clerk Organization Roles (Org-Level)

Storage: Clerk session claims (Astro.locals.userRole) Roles: org:admin, org:member

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

Use Cases:

• Organization settings
• Team management
• Org-specific features
• Multi-tenant access control

Unified API

The role guard system works with both role systems through a unified API:

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

Role Protection Pattern Comparison

The project offers three complementary patterns for role-based access control. Choose based on your specific needs:

Pattern	Best For	Implementation	When to Use
Auth Layout Props	Entire page protection	<Auth requiredRoles={[...]}/>	Admin pages, role-specific sections
requireRole() Helper	Page-level redirection	await requireRole(...)	API routes, forced redirects
RoleGuard Components	Section visibility	<RoleGuard allowedRoles={[...]}/>	Conditional content, mixed pages

Auth Layout Props

Declarative page protection using layout props

---
import Auth from '#layouts/Auth.astro'
const requiredRoles: AnyRole[] = ['admin', 'super_admin']
---

<Auth pageTitle="Admin Dashboard" requiredRoles={requiredRoles}>
  <!-- Entire page content protected -->
</Auth>

{
  /* The Auth layout denies in place (shows an "insufficient permissions" notice
    and withholds the page) — it cannot redirect. For a redirect, guard in the
    page's own frontmatter with redirectUnauthorized(Astro, requiredRoles). */
}

Advantages:

• ✅ Declarative and self-documenting
• ✅ Automatic error handling
• ✅ Performance optimized (parallel checks)
• ✅ Custom redirect URLs

See: Auth Layout Role Guards Guide

requireRole() Helper

Imperative role checking with redirection

---
import { requireRole } from '#utils/roles'

// Check role and redirect if unauthorized
await requireRole(Astro.locals, ['admin'], Astro.redirect)
---

<!-- Page content (only reached if authorized) -->

Advantages:

• ✅ Fine-grained control
• ✅ Hierarchical privilege escalation
• ✅ Custom redirect logic
• ✅ Works in API endpoints

See: Page-Level Protection Guide

RoleGuard Components

Component-based conditional rendering

---
import RoleGuard from '#components/astro/RoleGuard.astro'
---

<h1>Public Content</h1>

<RoleGuard allowedRoles={['admin']}>
  <h2>Admin-Only Section</h2>
</RoleGuard>

Advantages:

• ✅ Section-level protection
• ✅ Multiple guards per page
• ✅ Conditional content rendering
• ✅ No redirects (just hides content)

See: This guide (below)

Recommendation

• Page protection → Use Auth Layout Props or requireRole()
• Section visibility → Use RoleGuard components
• API endpoints → Use requireRole()
• Mixed content → Combine patterns as needed

Utility Functions

canViewContent()

Primary role-checking function - Returns boolean indicating if user can view content.

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

Basic Usage

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

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

{canViewAdmin && <AdminPanel />}

With Options

---
const canViewAdmin = await canViewContent(Astro.locals, ['admin', 'super_admin'], {
  fetchFromSupabase: true, // Fetch role from DB if not in locals
  cacheTTL: 120000, // Cache for 2 minutes (default: 1 min)
})
---

Return Value:

• true - User has at least ONE of the allowed roles
• false - User lacks all allowed roles OR not authenticated

---

canViewContentDetailed()

Enhanced version - Returns detailed authorization result with debugging info.

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

Usage

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

const result = await canViewContentDetailed(Astro.locals, ['admin'])

if (!result.allowed) {
  console.log('Access denied:', result.reason)
  console.log('User role:', result.userRole)
}
---

Return Type

interface RoleCheckResult {
  allowed: boolean // Whether access is granted
  userRole: AnyRole | null // User's current role
  reason?: string // Reason for denial (if denied)
}

Example Results

// Access granted
{ allowed: true, userRole: 'admin' }

// Access denied - wrong role
{
  allowed: false,
  userRole: 'member',
  reason: 'User role "member" not in allowed roles: admin, super_admin'
}

// Access denied - not authenticated
{
  allowed: false,
  userRole: null,
  reason: 'User not authenticated'
}

---

requireRole()

Page-level protection - Throws 403 error if user lacks required role.

Note

For comprehensive page-level protection documentation, see the dedicated Page-Level Protection Guide which covers hierarchical privilege escalation, exact role matching, and security best practices.

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

src/pages/super-admin/index.astro

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

// Protect entire page - throws if unauthorized
await requireRole(Astro.locals, ['super_admin'])
---

<html>
  <body>
    <h1>Super Admin Dashboard</h1>
    <!-- All content protected - only renders if check passes -->
  </body>
</html>

Tip

Create src/pages/403.astro for custom forbidden pages. Astro automatically converts thrown errors to error pages.

---

getUserRole()

Extracts user role from Astro.locals with optional Supabase fallback.

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'
---

Fetch Priority:

1. Astro.locals.userRole (Clerk org role from middleware)
2. Supabase query (if fetchFromSupabase === true)
3. null (if not authenticated)

---

hasAnyRole() & hasAllRoles()

Semantic aliases for role checking with explicit OR/AND logic.

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

hasAnyRole() - OR Logic

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

// User needs to be admin OR super_admin
const isStaff = await hasAnyRole(Astro.locals, ['admin', 'super_admin'])
---

{isStaff && <StaffTools />}

hasAllRoles() - AND Logic

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

// User must be admin (single role check)
const isAdmin = await hasAllRoles(Astro.locals, ['admin'])
---

Caution

Currently only works for single-role checks. Multi-role AND logic across different role systems (Supabase + Clerk) is planned for future enhancement.

---

Helper Functions

isValidRole()

Type guard - Validates if string is a valid role.

const userInput = 'admin'

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

formatRoleForDisplay()

Human-readable labels - Converts role identifiers to display names.

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

Wrapper Components

Astro RoleGuard

Server-side component for Astro pages - performs authorization server-side (zero client JavaScript).

Props

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)
}

Basic Usage

---
import RoleGuard from '#components/astro/RoleGuard.astro'
---

<RoleGuard allowedRoles={['admin', 'super_admin']}>
  <div class="admin-panel">
    <h2>Admin Controls</h2>
    <button>Delete All Users</button>
  </div>
</RoleGuard>

With Fallback

<RoleGuard
  allowedRoles={['super_admin']}
  fallback="You need super admin permissions to view this content."
>
  <DangerZone />
</RoleGuard>

Debug Mode

<RoleGuard allowedRoles={['admin']} debug={true}>
  <AdminPanel />
</RoleGuard>

<!-- Renders in development:
🔍 RoleGuard Debug
User Role: member
Allowed Roles: admin, super_admin
Access: ❌ Denied
-->

---

React RoleGuard

Client-side component for React - requires server-fetched role data as props.

Props

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
}

IMPORTANT

React components cannot access Astro.locals directly. Always fetch roles server-side in the Astro page and pass as props.

Server-Side Setup

src/pages/dashboard.astro

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

// Fetch role server-side
const userRole = await getUserRole(Astro.locals, true)
---

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

React Component

src/components/react/Dashboard.tsx

import { RoleGuard } from '#components/react/RoleGuard'
import type { AnyRole } from '#utils/role-types'

interface Props {
  userRole: AnyRole | null
}

export function Dashboard({ userRole }: Props) {
  return (
    <div>
      <h1>Dashboard</h1>

      {/* Admin-only content */}
      <RoleGuard
        userRole={userRole}
        allowedRoles={['admin', 'super_admin']}
        fallback={<p>Admin access required</p>}
      >
        <AdminSettings />
      </RoleGuard>

      {/* All authenticated users */}
      <RoleGuard userRole={userRole} allowedRoles={['member', 'admin', 'super_admin']}>
        <UserContent />
      </RoleGuard>
    </div>
  )
}

Custom Fallback

<RoleGuard
  userRole={userRole}
  allowedRoles={['super_admin']}
  fallback={
    <div className="access-denied">
      <h2>Access Denied</h2>
      <p>Contact your administrator for super admin access.</p>
      <a href="/support">Request Access</a>
    </div>
  }
>
  <SuperAdminPanel />
</RoleGuard>

Common Patterns

1. Tiered Content Access

Show different content based on role hierarchy.

---
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>
  )
}

2. Mixed Role Types

Support both Supabase and Clerk roles in same page.

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

3. Nested Protection

Combine page-level and component-level guards for granular control.

See Page-Level Protection Guide for more examples and security best practices.

---
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>

4. Conditional Navigation

Show/hide navigation items based on role.

---
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="/dashboard/users">Users</a>}
</nav>

5. Form Field Protection

Hide sensitive form fields based on role.

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>
  )
}

Performance Tips

1. Cache Configuration

Default cache TTL is 1 minute. Adjust based on your needs:

---
// 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 })
---

2. Minimize Supabase Queries

Clerk org roles are in Astro.locals (no DB query). Use them when possible:

---
// ✅ 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 })
---

3. Pre-fetch in Middleware

For protected routes, pre-fetch Supabase roles in middleware:

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

Then role guards skip the DB query entirely.

4. Batch Role Checks

When rendering lists, fetch role once and reuse:

---
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} />
  )
}

Troubleshooting

Issue: Role Not Detected

Symptoms: Content hidden even though user has correct role

Causes:

1. Supabase role not synced from Clerk
2. Typo in role name
3. Cache showing stale data

Solutions:

Debug Mode

---
// Enable debug mode to see what's happening
---

<RoleGuard allowedRoles={['admin']} debug={true}>
  <Content />
</RoleGuard>

<!-- Check output:
User Role: member (expected: admin)
Allowed Roles: admin
Access: Denied
-->

Clear Cache

// Clear cache and try again
import { clearRoleCache } from '#utils/role-guard'
clearRoleCache(userId)

Force Fresh Query

---
// Force fresh Supabase query
const result = await canViewContentDetailed(Astro.locals, ['admin'], {
  fetchFromSupabase: true,
  cacheTTL: 0,
})

console.log('Role check result:', result)
---

Issue: “User not found in Supabase”

Symptoms: PGRST116 error or null role returned

Cause: Clerk user not yet synced to Supabase database

Solution: User creation happens automatically via webhook. The UserInfo.astro component handles this with upsert logic (see: src/components/astro/UserInfo.astro:55-64).

Issue: React Component Not Rendering

Symptoms: RoleGuard in React shows nothing

Cause: userRole prop not passed from server

Solution:

---
// 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 />

Issue: Performance Degradation

Symptoms: Page loads slowly with many role checks

Solutions:

1. Reduce cache TTL (if roles change frequently)
2. Increase cache TTL (if roles are stable)
3. Pre-fetch roles in middleware for protected routes
4. Use Clerk org roles instead of Supabase roles when possible

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

Migration Guide

Replacing Manual Role Checks

Before (Manual)

---
const supabase = getSupabaseServiceRole()
const { data } = await supabase.from('users').select('role').eq('clerk_id', userId).single()

const isAdmin = data?.role === 'admin' || data?.role === 'super_admin'
---

{isAdmin && <AdminPanel />}

After (Role Guard)

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

const isAdmin = await canViewContent(Astro.locals, ['admin', 'super_admin'])
---

{isAdmin && <AdminPanel />}

Benefits:

• ✅ 80% less code
• ✅ Type-safe
• ✅ Automatic caching
• ✅ Better error handling
• ✅ Consistent with project patterns

Best Practices

Security

1. Never trust client-side - Always fetch roles server-side
2. Defense in depth - Combine role guards with RLS policies and middleware
3. Audit logging - Use canViewContentDetailed() for security audits
4. Principle of least privilege - Grant minimum necessary permissions

Code Organization

1. Component-level guards for granular UI control
2. Page-level guards (requireRole) for route protection
3. Middleware guards for API endpoint protection
4. Consistent role naming - Use constants from #utils/role-types

Testing

1. Mock Astro.locals in tests
2. Test both authorized and unauthorized cases
3. Verify fallback content renders
4. Check accessibility attributes (role, aria-*)

Summary

The role-based visibility system provides:

🎯 Unified API

Single interface for both Supabase and Clerk roles

🔒 Server-Side Security

Zero client JavaScript, all checks happen server-side

⚡ Auto-Caching

Configurable cache TTL (default: 1 minute)

🛡️ Type Safety

Full TypeScript support with strict type checking

🧪 Well-Tested

54+ unit and component tests ensure reliability

👨‍💻 Developer-Friendly

Matches existing project patterns and conventions

Quick Reference:

• Simple checks: canViewContent()
• Page protection: requireRole()
• Debugging: canViewContentDetailed()
• Astro components: <RoleGuard>
• React components: <RoleGuard userRole={...}>

For implementation details, see the role-based visibility system implementation plan.

---

Note

Questions or Issues? File an issue with the role-guard label on GitHub.