Permission System Documentation

Complete guide to the DBK Gaming Platform permission and rank system.

---

Overview

The platform uses a two-tiered permission system:

1. Rank-Based Permissions: Users have a rank (MEMBER, MODERATOR, ADMIN) that grants baseline permissions
2. Granular Permission Overrides: Individual permissions can be granted or revoked to override rank defaults

This provides flexibility to:

• Grant moderators access to specific features without full admin access
• Revoke specific permissions from users who otherwise have high ranks
• Create custom permission sets for specific users

---

Rank System

Rank Hierarchy

Rank Enforcement

• Higher ranks inherit all permissions of lower ranks
• Users cannot promote others to their own rank or higher
• Users cannot modify the rank of users at or above their level
• ADMINs can promote users to MODERATOR
• ADMINs cannot demote other ADMINs

User Rank Assignment

Every user automatically receives a MEMBER rank upon first login. ADMINs can promote users through:

API Endpoint: PATCH /api/ranks/users/:id

Example:

{
  "rank": "MODERATOR"
}

---

Permission Types

Platform Permissions

These permissions control access to platform-wide features:

Forum Permissions

These permissions control forum access and moderation:

Game Server Permissions

These permissions control game server submissions:

Server-Specific Permissions

These permissions control per-server access:

---

Granular Permission Overrides

Admins can grant or revoke individual permissions to fine-tune access.

Grant Permission

API Endpoint: POST /api/ranks/permissions

Example - Grant forum moderation for specific category:

{
  "userId": "123456789012345678",
  "permission": "moderate_category",
  "granted": true,
  "scope": "category_clxyz123"
}

Example - Revoke announcement management:

{
  "userId": "123456789012345678",
  "permission": "manage_announcements",
  "granted": false,
  "scope": null
}

Permission Scopes

Permissions can be scoped to specific resources:

• Category-scoped: Permission applies only to a specific forum category
  • scope: "category_id"
• Server-scoped: Permission applies only to a specific Discord server
  • scope: "server_id"
• Global: Permission applies platform-wide
  • scope: null

Example: A user could have MODERATE_CATEGORY permission for the "General Discussion" category but not other categories.

---

Server Membership System

Each Discord server listing can have its own members with server-specific ranks.

Server Ranks

Server Member Management

Add Member: POST /api/servers/:id/members

{
  "userId": "user_id",
  "rank": "SERVER_MEMBER"
}

Update Member Rank: PATCH /api/servers/:id/members/:userId

{
  "rank": "SERVER_ADMIN"
}

Remove Member: DELETE /api/servers/:id/members/:userId

Server Access Control

• Only SERVER_ADMINs and SERVER_OWNERs can manage members
• Only SERVER_OWNERs can promote users to SERVER_ADMIN
• Platform ADMINs can override all server permissions
• Server members can view private server information

---

Forum Category Permissions

Forum categories can have custom permission requirements.

Category-Level Access Control

Each forum category has:

• minReadRank: Minimum rank to view threads (default: MEMBER)
• minWriteRank: Minimum rank to create threads (default: MEMBER)

Example:

{
  "name": "Staff Discussions",
  "slug": "staff",
  "minReadRank": "MODERATOR",
  "minWriteRank": "MODERATOR"
}

Category Permission Overrides

Admins can create per-category permission overrides for specific ranks:

Model: ForumCategoryPermission

Fields:

• categoryId: Category this permission applies to
• rank: Rank this permission applies to
• canRead: Can view threads (default: true)
• canWrite: Can create threads/posts (default: true)
• canModerate: Can pin/lock/delete (default: false)

Example: Allow MEMBERs to read but not write in "Announcements" category:

{
  "categoryId": "category_announcements",
  "rank": "MEMBER",
  "canRead": true,
  "canWrite": false,
  "canModerate": false
}

---

Permission Resolution

When checking if a user can perform an action, the system follows this priority:

1. Platform ADMIN: Always has full access
2. Granular Permission Override: Check if user has specific permission granted/revoked
3. Rank-Based Permission: Check if user's rank grants the permission
4. Category-Specific Permission: Check category permission overrides
5. Ownership: Check if user owns the resource (can edit own posts, etc.)

Example Permission Check Flow:

Can user create thread in category "General Discussion"?

1. Is user ADMIN? → NO, continue
2. Does user have REVOKED "create_thread" for this category? → NO, continue
3. Does user have GRANTED "create_thread" for this category? → NO, continue
4. Does user's rank >= category.minWriteRank? → YES (MEMBER >= MEMBER)
   → ALLOW

---

Permission Checking Utilities

The platform provides utility functions for permission checks:

Backend Functions

checkUserPermission(userId, permission, scope)

• Returns: { allowed: boolean, reason?: string }
• Checks if user has specific permission with optional scope

hasRank(userId, minRank)

• Returns: boolean
• Checks if user has at least the specified rank

checkServerMembership(userId, serverId, minRank)

• Returns: boolean
• Checks if user is a member of server with at least minRank

canAccessCategory(userId, categoryId, action)

• Returns: { allowed: boolean, reason?: string }
• Checks if user can perform action ('read' or 'write') in category

canModerateCategory(userId, categoryId)

• Returns: boolean
• Checks if user can moderate specific category

Frontend Hooks

useAuth() context provides:

const { user, hasRank, hasPermission } = useAuth();

if (hasRank('MODERATOR')) {
  // Show moderation UI
}

if (hasPermission('manage_announcements')) {
  // Show announcement management
}

---

Middleware

The backend uses middleware to enforce permissions on routes:

requireAuth

Requires user to be authenticated.

router.get('/protected', requireAuth, async (req, res) => {
  // req.user is available
});

requireRank(minRank)

Requires user to have at least specified rank.

router.post('/admin/action', requireAuth, requireRank('ADMIN'), async (req, res) => {
  // Only ADMINs can access
});

requirePermission(permission, scopeKey)

Requires user to have specific permission.

router.post('/forum/moderate', requireAuth, requirePermission('moderate_forum'), async (req, res) => {
  // Only users with moderate_forum permission
});

requireServerMembership(minRank, paramKey)

Requires user to be a server member with minimum rank.

router.get('/servers/:id/settings', requireAuth, requireServerMembership('SERVER_ADMIN', 'id'), async (req, res) => {
  // Only SERVER_ADMINs of this server
});

---

Audit Logging

All permission changes are logged to AdminAuditLog:

Logged Actions

• UPDATE_USER_RANK: User rank changed
• GRANT_PERMISSION: Permission granted to user
• REVOKE_PERMISSION: Permission revoked from user

Audit Log Entry:

{
  "id": "log_id",
  "adminId": "admin_user_id",
  "action": "UPDATE_USER_RANK",
  "targetType": "user",
  "targetId": "target_user_id",
  "metadata": "{\"oldRank\":\"MEMBER\",\"newRank\":\"MODERATOR\"}",
  "createdAt": "2024-01-01T00:00:00.000Z"
}

---

Caching

Permissions are cached for performance:

• User Rank Cache: 5 minute TTL
• User Permissions Cache: 5 minute TTL
• Server Membership Cache: 5 minute TTL

Cache is automatically invalidated when:

• User rank is changed
• Permission is granted/revoked
• Server membership is modified

---

Security Considerations

Best Practices

1. Principle of Least Privilege: Grant minimum permissions needed
2. Regular Audits: Review audit logs for suspicious permission changes
3. Scope Permissions: Use scoped permissions when possible (category-specific, server-specific)
4. Test Permissions: Verify permission enforcement in development before production

Security Rules

• Users cannot promote others to or above their own rank
• Users cannot modify permissions for users at or above their level
• Platform ADMINs can override all permissions
• Permission checks happen on both frontend (UX) and backend (security)
• All permission changes are logged with admin ID and timestamp

---

Migration from Legacy System

The platform previously used a simple User.role field with only "MEMBER" and "ADMIN" values.

Migration Process

1. Automatic Migration: All users receive a UserRank record on first access

   • Existing ADMIN users → ADMIN rank (level 100)
   • All other users → MEMBER rank (level 1)

2. Manual Migration Script: scripts/migrate-user-ranks.js

   node scripts/migrate-user-ranks.js
   

3. Backward Compatibility: User.role field still exists for legacy code but should not be used

Deprecation Timeline

• Current: Both User.role and UserRank exist
• Future: User.role will be removed in a future update
• Action Required: Update all code to use rank-based permission checks

---

Examples

Example 1: Promote User to Moderator

// Admin promotes user
const response = await fetch('/api/ranks/users/123456789', {
  method: 'PATCH',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({ rank: 'MODERATOR' })
});

const user = await response.json();
console.log(user.rank); // { rank: 'MODERATOR', level: 50 }

Example 2: Grant Category Moderation Permission

// Admin grants category-specific moderation
const response = await fetch('/api/ranks/permissions', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    userId: '123456789',
    permission: 'moderate_category',
    granted: true,
    scope: 'category_general'
  })
});

Example 3: Check Permission in Frontend

import { useAuth } from '@/contexts/AuthContext';

function ModerateButton({ categoryId }) {
  const { user, hasPermission } = useAuth();

  if (!hasPermission('moderate_category', categoryId)) {
    return null; // Hide button if no permission
  }

  return <button>Moderate</button>;
}

Example 4: Add User as Server Admin

// Server owner adds user as admin
const response = await fetch('/api/servers/987654321/members', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    userId: '123456789',
    rank: 'SERVER_ADMIN'
  })
});

---

Troubleshooting

User Can't Access Feature They Should Have Access To

1. Check user rank: GET /api/ranks/users?search=username
2. Check user permissions: Look for revoked permissions
3. Check cache: Permission cache may be stale (wait 5 minutes or clear cache)
4. Check category permissions: If forum-related, check category-specific permissions

Permission Changes Not Taking Effect

1. Clear cache: Invalidate user permission cache
2. Check audit logs: Verify permission change was logged
3. Verify scope: Ensure scope matches (null vs specific ID)
4. Refresh session: User may need to log out and back in

Cannot Promote User

1. Verify your rank: You must be higher rank than target
2. Verify target rank: Cannot promote users at or above your level
3. Verify target rank level: Cannot promote to your rank or higher

---

API Reference

See API.md for complete API documentation of permission endpoints:

• GET /api/ranks/users
• PATCH /api/ranks/users/:id
• GET /api/ranks/permissions
• POST /api/ranks/permissions
• DELETE /api/ranks/permissions/:id

---

Last Updated: February 17, 2026