Your favorite shift management application!
/**
* Admin Role Helpers
*
* Utility functions for checking and enforcing admin permissions.
* Used throughout the application to protect admin-only routes and features.
*/
import type { User } from "@/lib/auth";
import { APIError } from "better-auth/api";
/**
* Valid admin roles in the system
*/
export const ADMIN_ROLES = ["admin", "superadmin"] as const;
export type AdminRole = (typeof ADMIN_ROLES)[number];
/**
* Check if a user has an admin role (admin or superadmin)
*
* @param user - The user object (can be null for unauthenticated users)
* @returns boolean - true if user is admin or superadmin
*/
export function isAdmin(user: User | null | undefined): boolean {
if (!user?.role) return false;
return ADMIN_ROLES.includes(user.role as AdminRole);
}
/**
* Check if a user has the superadmin role specifically
*
* @param user - The user object (can be null for unauthenticated users)
* @returns boolean - true if user is superadmin
*/
export function isSuperAdmin(user: User | null | undefined): boolean {
return user?.role === "superadmin";
}
/**
* Require admin role or throw an error
* Use this in API routes to protect admin-only endpoints
*
* @param user - The user object (can be null for unauthenticated users)
* @throws APIError with status 403 if user is not an admin
*/
export function requireAdmin(
user: User | null | undefined
): asserts user is User & { role: AdminRole } {
if (!isAdmin(user)) {
throw new APIError("FORBIDDEN", {
message: "Admin access required",
});
}
}
/**
* Require superadmin role or throw an error
* Use this in API routes to protect superadmin-only endpoints
*
* @param user - The user object (can be null for unauthenticated users)
* @throws APIError with status 403 if user is not a superadmin
*/
export function requireSuperAdmin(
user: User | null | undefined
): asserts user is User & { role: "superadmin" } {
if (!isSuperAdmin(user)) {
throw new APIError("FORBIDDEN", {
message: "Superadmin access required",
});
}
}
/**
* Get user's admin level (for display purposes)
*
* @param user - The user object
* @returns string - "superadmin", "admin", or "user"
*/
export function getAdminLevel(
user: User | null | undefined
): "superadmin" | "admin" | "user" {
if (!user?.role) return "user";
if (user.role === "superadmin") return "superadmin";
if (user.role === "admin") return "admin";
return "user";
}
/**
* Admin Permission Check Functions
*
* These functions determine what actions an admin can perform.
* Used by both API routes (server-side) and React hooks (client-side).
* All checks are synchronous - no async API calls needed.
*/
/**
* Check if admin can edit a target user
*
* Rules:
* - Superadmin: Can edit anyone
* - Admin: Can edit only regular users (role: "user" or null)
* - Cannot edit self (use profile page instead)
*
* @param adminUser - The admin performing the action
* @param targetUser - The user being edited
* @returns boolean - true if admin can edit target user
*/
export function canEditUser(
adminUser: User | null | undefined,
targetUser: User | null | undefined
): boolean {
if (!isAdmin(adminUser) || !targetUser) return false;
// Superadmin can edit anyone
if (isSuperAdmin(adminUser)) return true;
// Admin can only edit regular users
const targetRole = targetUser.role || "user";
return targetRole === "user";
}
/**
* Check if admin can delete a target user
*
* Rules:
* - Only superadmin can delete users
* - Cannot delete self
*
* @param adminUser - The admin performing the action
* @param targetUser - The user being deleted
* @returns boolean - true if admin can delete target user
*/
export function canDeleteUser(
adminUser: User | null | undefined,
targetUser: User | null | undefined
): boolean {
if (!isSuperAdmin(adminUser) || !targetUser) return false;
if (adminUser!.id === targetUser.id) return false;
return true;
}
/**
* Check if admin can ban a target user
*
* Rules:
* - Only superadmin can ban users
* - Cannot ban self
* - Cannot ban other superadmins
*
* @param adminUser - The admin performing the action
* @param targetUser - The user being banned
* @returns boolean - true if admin can ban target user
*/
export function canBanUser(
adminUser: User | null | undefined,
targetUser: User | null | undefined
): boolean {
if (!isSuperAdmin(adminUser) || !targetUser) return false;
if (adminUser!.id === targetUser.id) return false;
if (targetUser.role === "superadmin") return false;
return true;
}
/**
* Check if admin can change a user's role
*
* Rules:
* - Only superadmin can change roles
* - Cannot change own role
*
* @param adminUser - The admin performing the action
* @param targetUser - The user whose role is being changed
* @returns boolean - true if admin can change target user's role
*/
export function canChangeUserRole(
adminUser: User | null | undefined,
targetUser: User | null | undefined
): boolean {
if (!isSuperAdmin(adminUser) || !targetUser) return false;
if (adminUser!.id === targetUser.id) return false;
return true;
}
/**
* Check if admin can reset a user's password
*
* Rules:
* - Both admin and superadmin can reset passwords
* - Cannot reset own password (use change password instead)
* - Admin cannot reset superadmin passwords
*
* @param adminUser - The admin performing the action
* @param targetUser - The user whose password is being reset
* @returns boolean - true if admin can reset target user's password
*/
export function canResetPassword(
adminUser: User | null | undefined,
targetUser: User | null | undefined
): boolean {
if (!isAdmin(adminUser) || !targetUser) return false;
if (adminUser!.id === targetUser.id) return false;
// Superadmin can reset anyone's password
if (isSuperAdmin(adminUser)) return true;
// Admin cannot reset superadmin passwords
if (targetUser.role === "superadmin") return false;
return true;
}
/**
* Check if admin can manage calendar operations
*
* Rules:
* - View: Both admin and superadmin
* - Delete: Only superadmin
*
* @param adminUser - The admin performing the action
* @param operation - The operation being performed ('view' or 'delete')
* @returns boolean - true if admin can perform the operation
*/
export function siteAdminCanManageCalendar(
adminUser: User | null | undefined,
operation: "view" | "delete"
): boolean {
if (!isAdmin(adminUser)) return false;
if (operation === "view") return true;
// Delete requires superadmin
return isSuperAdmin(adminUser);
}
/**
* Check if admin can edit a calendar
*
* Rules:
* - Both admin and superadmin can edit calendars
* - Can edit name, color, guest permission
* - Cannot change owner via edit (use transfer instead)
*
* @param adminUser - The admin performing the action
* @returns boolean - true if admin can edit calendars
*/
export function siteAdminCanEditCalendar(adminUser: User | null | undefined): boolean {
return isAdmin(adminUser);
}
/**
* Check if admin can delete a calendar
*
* Rules:
* - Only superadmin can delete calendars
*
* @param adminUser - The admin performing the action
* @returns boolean - true if admin can delete calendars
*/
export function siteAdminCanDeleteCalendar(adminUser: User | null | undefined): boolean {
return isSuperAdmin(adminUser);
}
/**
* Check if admin can transfer calendar ownership
*
* Rules:
* - Both admin and superadmin can transfer calendars
* - Can transfer any calendar (orphaned or owned)
*
* @param adminUser - The admin performing the action
* @returns boolean - true if admin can transfer calendars
*/
export function canTransferCalendar(
adminUser: User | null | undefined
): boolean {
return isAdmin(adminUser);
}
/**
* Check if admin can assign orphaned calendars
*
* Rules:
* - Both admin and superadmin can assign calendars
*
* @param adminUser - The admin performing the action
* @returns boolean - true if admin can assign orphaned calendars
*/
export function canAssignOrphanedCalendar(
adminUser: User | null | undefined
): boolean {
return isAdmin(adminUser);
}
/**
* Check if admin can view audit logs
*
* Rules:
* - Both admin and superadmin can view logs
*
* @param adminUser - The admin performing the action
* @returns boolean - true if admin can view audit logs
*/
export function canViewAuditLogs(adminUser: User | null | undefined): boolean {
return isAdmin(adminUser);
}
/**
* Check if admin can delete audit logs
*
* Rules:
* - Only superadmin can delete logs
*
* @param adminUser - The admin performing the action
* @returns boolean - true if admin can delete audit logs
*/
export function canDeleteAuditLogs(
adminUser: User | null | undefined
): boolean {
return isSuperAdmin(adminUser);
}
/**
* Check if admin can create new users from the admin panel.
*
* Rules:
* - Both admin and superadmin can create users
* - Only superadmin may assign a role other than "user" at creation time
* (mirrors canChangeUserRole's superadmin-only restriction)
*
* @param adminUser - The admin performing the action
* @param role - The role to assign to the new user, if any (omit to just check base access)
* @returns boolean - true if admin can create a user with the given role
*/
export function canCreateUser(
adminUser: User | null | undefined,
role?: string
): boolean {
if (!isAdmin(adminUser)) return false;
if (role !== undefined && role !== "user") return isSuperAdmin(adminUser);
return true;
}
/**
* Check if admin can view or change instance-wide system settings
* (e.g. whether the update check runs and who sees its banner).
*
* Rules:
* - Both admin and superadmin can manage system settings
*
* @param adminUser - The admin performing the action
* @returns boolean - true if admin can manage system settings
*/
export function canManageSystemSettings(
adminUser: User | null | undefined
): boolean {
return isAdmin(adminUser);
}