Improve documentation for BuiltInRoles

src/lib/auth/server.ts

@@ -3,18 +3,10 @@ import '@/node-only'
 import clientPromise from '../db'
 import { AppPermissions, Role } from '../db/models/Role'
 import User from '../db/models/User'
-import { mergePermission, UnauthedPerms } from './shared'
+import { BuiltInRoles, mergePermission, UnauthedPerms } from './shared'
 
 export * from './shared'
 
-const BuiltInRoles = {
-	'@@view-as': {
-		administration: {
-			role: true,
-		},
-	},
-} satisfies Record<`@@${string}`, AppPermissions>
-
 export async function getUserPerms(user: User | null): Promise<AppPermissions> {
 	const roles = [
 		...(user ? ['hacker'] : []),

src/lib/auth/shared.ts

@@ -14,6 +14,31 @@ export const UnauthedPerms: AppPermissions = {
 	post: true,
 }
 
+/**
+ * Types of roles:
+ *
+ * * Built-In: roles that are temporarily assigned by certain mechanisms
+ * to achieve a certain purpose. These roles cannot be managed by admins.
+ * * Unauthed: the base role that all users, including unauthenticated
+ * ones, are granted. This role cannot be managed by admins.
+ * * hacker: the base role that every authenticated user is granted.
+ * The permissions of this role can be changed by admins, but it cannot be
+ * deleted.
+ * * Database: roles created and fully managed by admins.
+ */
+export const BuiltInRoles = {
+	/**
+	 * A role temporarily assigned to users who are viewing as other roles.
+	 * This role has the neccessary permissions to ensure that the user
+	 * can restore back to their previous roles.
+	 */
+	'@@view-as': {
+		administration: {
+			role: true,
+		},
+	},
+} satisfies Record<`@@${string}`, AppPermissions>
+
 export function hasPermission(
 	granted: AppPermissions,
 	required: AppPermissions,