Permissions

The Permission entity defines granular access controls within the Wrkbelt platform. It is a core component of the role-based access control (RBAC) system, allowing for fine-grained control over user capabilities.

note

The permission system is designed to be extensible and will evolve with the platform. The permissions documented here represent the current set at the time of writing. As new features are added and the platform grows, additional permissions will be introduced and existing ones may be refined.

Schema Definition

type Permission = {
  // Base Properties
  _id: string; // MongoDB ObjectId
  name: AllPermissions; // Required, Unique, Predefined permission types
  description: string; // Required, Human-readable description

  // Timestamps
  createdAt: Date; // Auto-generated
  updatedAt: Date; // Auto-updated
} & BaseEntity;

Field Descriptions

Base Properties

Field	Type	Required	Unique	Description
_id	ObjectId	Yes	Yes	Unique identifier for the permission
name	AllPermissions	Yes	Yes	Predefined permission type from AllPermissions enum
description	string	Yes	No	Human-readable description of the permission

Timestamps

Field	Type	Description
createdAt	Date	Automatically set when the permission is created
updatedAt	Date	Automatically updated when the permission changes

Current Permission Categories

User Management

Permission	Description
VIEW_USERS	View Users
CREATE_USER	Create User
UPDATE_USER	Update User
DELETE_USER	Delete User
INVITE_USER	Invite User to signup
CREATE_ORG_MEMBER	Create an organization member

Permission Management

Permission	Description
VIEW_PERMISSIONS	View Permissions
CREATE_PERMISSION	Create Permission
UPDATE_PERMISSION	Update Permission
DELETE_PERMISSION	Delete Permission

Role Management

Permission	Description
VIEW_ROLES	View Roles
CREATE_ROLE	Create Role
UPDATE_ROLE	Update Role
DELETE_ROLE	Delete Role

Membership Management

Permission	Description
VIEW_MEMBERSHIPS	View Memberships
CREATE_MEMBERSHIP	Create Membership
UPDATE_MEMBERSHIP	Update Membership
DELETE_MEMBERSHIP	Delete Membership

Organization Management

Permission	Description
VIEW_ORGANIZATIONS	View Organizations
CREATE_ORGANIZATION	Create Organization
UPDATE_ORGANIZATION	Update Organization
DELETE_ORGANIZATION	Delete Organization

File Management

Permission	Description
VIEW_FILES	View Files
VIEW_FILE	View File
CREATE_FILE	Create File
UPDATE_FILE	Update File
DELETE_FILE	Delete File
DOWNLOAD_FILE	Download File
UPLOAD_FILE	Upload File
UPLOAD_MULTIPLE_FILES	Upload Multiple Files

BrandKit Management

Permission	Description
VIEW_BRANDKIT	View BrandKit
CREATE_BRANDKIT	Create BrandKit
UPDATE_BRANDKIT	Update BrandKit
DELETE_BRANDKIT	Delete BrandKit

Relationships

Primary Relationships

• Permission → Roles (Many-to-Many)
  • Permissions are assigned to roles
  • Each permission can be part of multiple roles
  • Relationship managed through Role entity's permissions array

Indirect Relationships

• Permission → Users (Many-to-Many through Roles and Memberships)
  • Users receive permissions through their roles
  • Permissions are checked against the user's current organization context

Permission Design Principles

1. Granularity

   • Each permission represents a single, specific action
   • Permissions are atomic and don't overlap in functionality
   • Complex operations may require multiple permissions

2. Clarity

   • Permission names are self-descriptive
   • Each permission has a clear, human-readable description
   • Permissions are grouped by functional area

3. Consistency

   • Similar operations across different resources use consistent naming
   • CRUD operations follow the pattern: VIEW*, CREATE*, UPDATE*, DELETE*
   • Special operations have unique, descriptive names

Security Considerations

1. Permission Checking

   • Permissions should be checked at both API and UI levels
   • Checks should consider the user's current organization context
   • Failed permission checks should be logged for security auditing (⚠️TODO⚠️)

2. Permission Assignment

   • Permissions can only be assigned to roles by authorized users
   • Some permissions may be restricted to system-level roles
   • Permission changes should be audited

3. Permission Inheritance

   • Permissions are inherited through role assignments
   • Users may have different permissions in different organizations
   • Permission checks should aggregate all applicable roles

Usage Examples

Permission Checking

Wrkbelt provides isomorphic utility functions for checking permissions, available in @wrkbelt/shared/utils-core-logic:

// Check a single permission
const canCreateUser = hasPermission(userPermissions, AllPermissions.CREATE_USER);

// Check multiple permissions
const canManageUsers = hasPermissions(userPermissions, [AllPermissions.CREATE_USER, AllPermissions.UPDATE_USER, AllPermissions.DELETE_USER]);

These utility functions are isomorphic and can be used in both frontend and backend code, ensuring consistent permission checking across the application.

Manual Permission Checking

// Check if user has permission through their roles
const hasPermission = user.memberships.find((m) => m.organization_id === currentOrgId).roles.some((role) => role.permissions.includes(AllPermissions.CREATE_USER));

Permission Validation

// Ensure permission name is valid
if (!Object.values(AllPermissions).includes(permissionName)) {
  throw new Error('Invalid permission name');
}