Role-Based Access Control

​

Role Hierarchy

​

User (Default)

• Create and edit own projects
• Register for events
• Send team invites
• Update profile settings
• No access to /admin routes

​

Moderator

• All user permissions
• Access to /admin/dashboard, /admin/users
• Hide/unhide users
• Ban users (excluding admins)
• View audit log (read-only in some implementations)

​

Admin

• All moderator permissions
• Unban users
• Delete user accounts
• Assign roles (user, moderator, admin)
• Review mentor applications
• Access audit log
• Manage Sanity Studio at /studio

​

Super Admin

ADMIN_USER_IDS="user_xxxxx,user_yyyyy"

• Clerk user IDs listed in ADMIN_USER_IDS are always treated as admins
• Bypasses database role column (source of truth for super-admins)
• Cannot be banned, hidden, deleted, or have role changed
• Identified by isSuperAdmin(clerkUserId) helper in lib/admin.ts:10-12

​

Role Assignment

​

Access Requirements

​

Role Management Interface

• Displays all users with moderator or admin role
• Search by display name or username
• Shows super-admin badge for ADMIN_USER_IDS entries
• Change role via dropdown or promote users by search

​

Set User Role

setUserRole({
  profileId: string,
  role: "user" | "moderator" | "admin"
})

1. Verify actor has admin permissions via isAdmin(userId)
2. Fetch target user profile
3. Check restrictions:
   • Cannot change super-admin roles
   • Cannot change your own role
   • No-op if same role
4. Update profiles.role in database
5. Log to adminAuditLog with oldRole and newRole metadata
6. Revalidate /admin/roles and /admin/users paths

{
  "action": "set_role",
  "actorProfileId": "...",
  "targetProfileId": "...",
  "metadata": {
    "oldRole": "user",
    "newRole": "moderator"
  }
}

​

Search for Users

• Minimum 2 characters required
• Case-insensitive search on displayName and username using ILIKE
• Returns up to 10 results
• Used for quick user lookup when assigning roles

​

Permission Helpers

​

isSuperAdmin(clerkUserId)

const superAdminIds = (process.env.ADMIN_USER_IDS ?? "")
  .split(",")
  .map((id) => id.trim())
  .filter(Boolean);

export function isSuperAdmin(clerkUserId: string): boolean {
  return superAdminIds.includes(clerkUserId);
}

​

getRole(clerkUserId)

export async function getRole(
  clerkUserId: string
): Promise<"user" | "moderator" | "admin"> {
  if (isSuperAdmin(clerkUserId)) return "admin";

  const profile = await db.query.profiles.findFirst({
    where: eq(profiles.clerkId, clerkUserId),
    columns: { role: true },
  });

  return profile?.role ?? "user";
}

​

isAdmin(clerkUserId)

export async function isAdmin(clerkUserId: string): Promise<boolean> {
  const role = await getRole(clerkUserId);
  return role === "admin";
}

​

isModerator(clerkUserId)

export async function isModerator(clerkUserId: string): Promise<boolean> {
  const role = await getRole(clerkUserId);
  return role === "admin" || role === "moderator";
}

​

canAccessAdmin(clerkUserId)

export async function canAccessAdmin(clerkUserId: string): Promise<boolean> {
  return isModerator(clerkUserId);
}

​

Session Helper

export const getAdminSession = cache(async () => {
  const { userId } = await auth();
  if (!userId) return null;

  const canAccess = await canAccessAdmin(userId);
  if (!canAccess) return null;

  const role = await getRole(userId);
  return { userId, role };
});

​

Middleware Protection

// Admin area (moderators + admins)
if (req.nextUrl.pathname.startsWith("/admin")) {
  if (!userId || !(await canAccessAdmin(userId))) {
    return NextResponse.redirect(new URL("/", req.url));
  }
}

// Sanity Studio (admins only)
if (req.nextUrl.pathname.startsWith("/studio")) {
  if (!userId || !(await isAdmin(userId))) {
    return NextResponse.redirect(new URL("/", req.url));
  }
}

​

Admin Layout Navigation

• All moderators/admins: Dashboard, Users
• Admins only: Roles, Mentors, Audit Log

​

Permissions Matrix

​

Database Schema

role: userRoleEnum("role").default("user").notNull()

export const userRoleEnum = pgEnum("user_role", [
  "user",
  "moderator",
  "admin",
]);

​

Best Practices

1. Use moderator role for content moderation volunteers who don’t need full admin access
2. Reserve admin role for trusted maintainers who manage roles and review applications
3. Grant super-admin sparingly — only for platform owners who need immutable admin access
4. Audit role changes regularly via /admin/audit to track permission escalations
5. Never share super-admin Clerk IDs publicly or in client-side code (env var is server-only)