payload-gatekeeper

Payload Gatekeeper

Test Coverage & Quality

A comprehensive, production-ready permissions system with role-based access control, automatic permission generation, and flexible configuration options. Your collections' trusted guardian.

Features

• 🔐 Role-Based Access Control (RBAC) - Define roles with specific permissions
• 🎯 Automatic Permission Generation - Permissions created for all collections automatically
• 🔄 Permission Inheritance - Support for wildcard permissions (*, collection.*)
• 🛡️ Protected Roles - Prevent modification of critical system roles
• 👁️ UI Visibility Control - Separate UI visibility from CRUD operations
• 🎨 Flexible Role Assignment - Permission-based role assignment (users can only assign roles with permissions they possess)
• 🔌 Multiple Auth Collections - Support for multiple user types (admin users, customers, etc.)
• 📍 Flexible Field Placement - Place role field anywhere in your collections (tabs, sidebar, custom position)
• 🎭 Collection-Specific Role Visibility - Roles can be shown only for relevant collections
• 🎨 Custom Permissions - Define your own application-specific permissions in organized groups
• ⚡ Zero Config Start - Works out of the box with sensible defaults
• 🔧 Fully Typed - Complete TypeScript support

UI Overview

Payload Gatekeeper provides a clean and intuitive interface for managing roles and permissions:

Roles Management

The Roles collection showing system default roles - fully manageable through the UI

User Role Assignment

Assigning roles when creating new users - with searchable dropdown

Users with Roles

Users overview showing their assigned roles

Installation

npm install payload-gatekeeper
# or
yarn add payload-gatekeeper
# or
pnpm add payload-gatekeeper

Quick Start

// payload.config.ts
import { buildConfig } from 'payload'
import { gatekeeperPlugin } from 'payload-gatekeeper'

export default buildConfig({
  // ... your config
  plugins: [
    gatekeeperPlugin({
      // Minimal config - just enhance your admin collection
      collections: {
        'users': {
          enhance: true,
          autoAssignFirstUser: true,
        }
      },
      // Exclude collections from permission system entirely
      excludeCollections: ['special-config'] // These use their own access control
    })
  ]
})

First User Setup

When autoAssignFirstUser is enabled, the first user automatically receives the super_admin role:

The first user gets super admin privileges automatically

Configuration

Full Configuration Example

import { gatekeeperPlugin } from 'payload-gatekeeper'

export default buildConfig({
  plugins: [
    gatekeeperPlugin({
      // Configure specific collections
      collections: {
        'admin-users': {
          enhance: true,
          roleFieldPlacement: {
            tab: 'Security',      // Place in specific tab
            position: 'first',    // Position: 'first', 'last', 'sidebar', or number
          },
          autoAssignFirstUser: true,   // First user gets super_admin role
          defaultRole: undefined,      // No default role for admins
        },
        'customers': {
          enhance: true,
          roleFieldPlacement: {
            position: 'sidebar',  // Show in sidebar
          },
          autoAssignFirstUser: false,  // Don't make first customer super_admin
          defaultRole: 'customer',     // New signups get 'customer' role
        },
      },
      
      // Define system roles (in addition to super_admin)
      systemRoles: [
        {
          name: 'admin',
          label: 'Administrator',
          permissions: [
            // UI visibility permissions
            'users.manage',       // Shows Users in admin UI
            'products.manage',    // Shows Products in admin UI
            'media.manage',       // Shows Media in admin UI
            // CRUD permissions
            'users.*',           // All user operations
            'products.*',        // All product operations
            'media.*',           // All media operations
            // Exclude roles.* to prevent role management
          ],
          protected: false,      // Can be modified
          active: true,
          description: 'Full admin access without role management',
          visibleFor: ['admin-users'],  // Only visible for admin users
        },
        {
          name: 'editor',
          label: 'Content Editor',
          permissions: [
            'products.manage',    // Can see products in UI
            'products.read',
            'products.update',
            'media.*',
          ],
          active: true,
          description: 'Can edit content and media',
        },
        {
          name: 'customer',
          label: 'Customer',
          permissions: [
            'orders.read',        // Can view own orders (row-level handled separately)
            'customers.read',     // Can view own profile
            'customers.update',   // Can update own profile
          ],
          active: true,
          description: 'Default customer role',
          visibleFor: ['customers'],  // Only visible for customer users
        },
      ],
      
      // Optional: Exclude collections from permission system
      excludeCollections: ['public-pages'],
      
      // Environment-based options
      skipPermissionChecks: false,  // Set to true during seeding/migration
      syncRolesOnInit: process.env.SYNC_ROLES === 'true',
      
      // UI customization
      rolesGroup: 'Admin',  // Group name for Roles collection in admin panel (default: 'System')
      rolesSlug: 'roles',   // Custom slug for Roles collection (default: 'roles')
    })
  ]
})

Core Concepts

Public Access

Non-authenticated users automatically have configurable public access:

// Default behavior - public can read all non-auth collections
gatekeeperPlugin({})

// Custom public permissions
gatekeeperPlugin({
  publicRolePermissions: [
    '*.read',           // Read all collections
    'comments.create',  // Can create comments
    'reactions.create'  // Can add reactions
  ]
})

// Completely private system
gatekeeperPlugin({
  disablePublicRole: true  // No public access at all
})

Important: Auth-enabled collections (users, admins) are ALWAYS protected from public access, regardless of public permissions.

Role Management

The plugin automatically creates a Roles collection where you can manage all roles through the UI:

Creating a new editor role with specific permissions

Roles collection showing both system and custom roles

Permission Patterns

The plugin supports various permission patterns:

• * - Super admin with access to everything
• collection.* - All operations on a specific collection
• collection.read - Specific operation on a collection
• *.read - Read access to all collections
• collection.manage - UI visibility permission (controls whether collection appears in admin panel)

Protected Roles

Protected roles cannot be deleted and have restricted field updates. Only users with * permission can modify protected roles.

const superAdminRole = {
  name: 'super_admin',
  permissions: ['*'],
  protected: true,  // Cannot be deleted, limited updates
}

Protected super admin role showing the lock indicator and full permissions

UI Visibility vs CRUD Operations

The plugin separates UI visibility from CRUD operations:

• .manage permission - Controls whether a collection appears in the admin UI
• CRUD permissions (.read, .create, .update, .delete) - Control actual data operations

// User can see the collection in UI but only read data
permissions: ['products.manage', 'products.read']

// User can perform operations but collection is hidden in UI
permissions: ['products.create', 'products.update']

Custom Permissions

Define application-specific permissions that are automatically organized by namespace:

import { gatekeeper } from 'payload-gatekeeper'

export default buildConfig({
  plugins: [
    gatekeeper({
      customPermissions: [
        // Event Management permissions (namespace: event-management)
        {
          label: 'Export Events',
          value: 'event-management.export',
          description: 'Export event data to CSV/Excel'
        },
        {
          label: 'Import Events',
          value: 'event-management.import',
          description: 'Import events from external sources'
        },
        {
          label: 'Manage Templates',
          value: 'event-management.templates',
          description: 'Create and manage event templates'
        },
        
        // Marketing permissions (namespace: marketing)
        {
          label: 'Send Newsletters',
          value: 'marketing.newsletters',
          description: 'Send marketing newsletters to users'
        },
        {
          label: 'Manage Campaigns',
          value: 'marketing.campaigns',
          description: 'Create and manage marketing campaigns'
        },
        
        // Analytics permissions (namespace: analytics)
        {
          label: 'View Analytics',
          value: 'analytics.view',
          description: 'View platform analytics and metrics'
        },
        {
          label: 'Export Reports',
          value: 'analytics.export',
          description: 'Export analytics reports'
        }
      ]
    })
  ]
})

Using Custom Permissions

Custom permissions appear automatically in the Roles management UI, grouped by their namespace. Use them in your code:

// In API endpoints or hooks
import { checkPermission } from 'payload-gatekeeper'

export const exportEventHandler = async (req, res) => {
  const canExport = await checkPermission(
    req.payload,
    req.user.role,
    'event-management.export',
    req.user.id
  )
  
  if (!canExport) {
    return res.status(403).json({ error: 'Not authorized to export events' })
  }
  
  // Export logic here...
}

Namespace Formatting

The namespace (part before the dot) in the permission value is automatically extracted and formatted as the category:

• event-management.export → Category: "Event Management"
• backend-users.impersonate → Category: "Backend Users"
• user-profiles.manage → Category: "User Profiles"

This keeps your permissions organized in the UI without explicit grouping configuration.

Custom Permissions Structure

• Namespace: The part before the dot becomes the category (e.g., event-management)
• Operation: The part after the dot is the specific operation (e.g., export)
• Permissions: Each permission has:
  • label: Display name in the UI
  • value: Unique identifier with namespace.operation format
  • description: Optional helper text shown in the UI

Custom permissions integrate seamlessly with the existing permission system, supporting the same wildcards and inheritance patterns.

Permission-Based Role Assignment

Users can only assign roles whose permissions are a subset of their own:

• User with users.* and media.* can assign roles with users.read or media.update
• User with users.* cannot assign a role with products.* (they don't have product permissions)
• Only users with * permission can assign protected roles

Multiple Collections Support

The plugin is designed to work seamlessly with multiple auth-enabled collections. Each collection can have its own:

• Custom role field placement - Place the role field in tabs, sidebar, or specific positions
• Different default roles - Assign different default roles to different user types
• Auto-assignment rules - Configure which collections auto-assign super_admin to first user
• Independent permission checks - Each collection's users are evaluated based on their assigned roles

Why Multiple Collections?

Many applications need different types of users:

• Admin Users - Internal staff managing the platform
• Customers - End users of your application
• Vendors - Third-party sellers or service providers
• Partners - External collaborators with limited access

Each can have their own collection with tailored fields, while sharing the same role-based permission system.

Examples

Basic Setup with Single Admin Collection

gatekeeperPlugin({
  collections: {
    'users': {
      enhance: true,
      autoAssignFirstUser: true,
    }
  }
})

Multiple User Types with Custom Field Placement

gatekeeperPlugin({
  collections: {
    'admins': {
      enhance: true,
      roleFieldPlacement: { 
        tab: 'Security',        // Create/use 'Security' tab
        position: 'first'       // Place at the beginning of the tab
      },
      autoAssignFirstUser: true,
    },
    'customers': {
      enhance: true,
      roleFieldPlacement: { 
        position: 'sidebar'     // Show in the sidebar for easy access
      },
      defaultRole: 'customer',
    },
    'vendors': {
      enhance: true,
      roleFieldPlacement: {
        tab: 'Account',         // Place in existing 'Account' tab
        position: 2             // Place as third field (0-indexed)
      },
      defaultRole: 'vendor',
    },
    'partners': {
      enhance: true,
      roleFieldPlacement: {
        position: 'last'        // Place at the end of fields
      },
      defaultRole: 'partner',
    }
  },
  systemRoles: [
    // ... role definitions
  ]
})

Custom Role Field Configuration

You can further customize the role field for each collection:

gatekeeperPlugin({
  collections: {
    'users': {
      enhance: true,
      roleFieldConfig: {
        label: 'Access Level',           // Custom label
        admin: {
          description: 'Controls what this user can access in the system',
          position: 'sidebar',
          condition: (data) => data.active === true,  // Only show for active users
        }
      }
    }
  }
})

Seeding Users

Simple: First Admin User (with autoAssignFirstUser)

When autoAssignFirstUser: true is configured, you don't need to search for roles - the first user automatically gets super_admin:

// seed-admin.ts
import { getPayload } from 'payload'
import config from './payload.config'

async function seedFirstAdmin() {
  const payload = await getPayload({ config })

  try {
    // Check if any admin users exist
    const existingUsers = await payload.count({
      collection: 'users',
    })

    if (existingUsers.totalDocs > 0) {
      console.log('Admin users already exist, skipping seed')
      return
    }

    // Create the first admin user - automatically gets super_admin role!
    await payload.create({
      collection: 'users',
      data: {
        email: '[e-mail]',
        password: 'SecurePassword123!',
        // No need to set role - autoAssignFirstUser handles it
      },
    })

    console.log('✅ First admin user created with super_admin role')
  } catch (error) {
    console.error('Error seeding admin:', error)
  }

  process.exit(0)
}

seedFirstAdmin()

Advanced: Multiple Users with Specific Roles

Only search for roles when you need to create additional users with specific roles:

// seed-users.ts
async function seedUsers() {
  const payload = await getPayload({ config })

  try {
    // Find specific roles for additional users
    const editorRole = await payload.find({
      collection: 'roles',
      where: { name: { equals: 'editor' } },
      limit: 1,
    })

    const viewerRole = await payload.find({
      collection: 'roles',
      where: { name: { equals: 'viewer' } },
      limit: 1,
    })

    // Create editor user
    if (editorRole.docs.length > 0) {
      await payload.create({
        collection: 'users',
        data: {
          email: '[e-mail]',
          password: 'EditorPass123!',
          role: editorRole.docs[0].id,
        },
      })
    }

    // Create viewer user
    if (viewerRole.docs.length > 0) {
      await payload.create({
        collection: 'users',
        data: {
          email: '[e-mail]',
          password: 'ViewerPass123!',
          role: viewerRole.docs[0].id,
        },
      })
    }

    console.log('✅ Additional users created')
  } catch (error) {
    console.error('Error seeding users:', error)
  }
}

seedUsers()

Custom Permission Checks in Your Code

import { checkPermission, hasPermission } from 'payload-gatekeeper'

// In your custom endpoint or hook
async function myCustomEndpoint(req: PayloadRequest) {
  // Check if user has specific permission
  const canEdit = await checkPermission(
    req.payload,
    req.user.role,
    'products.update',
    req.user.id
  )
  
  if (!canEdit) {
    throw new Error('Unauthorized')
  }
  
  // Direct permission check (if you have the permissions array)
  const permissions = req.user.role?.permissions || []
  const canDelete = hasPermission(permissions, 'products.delete')
}

API Reference

Plugin Options

Option	Type	Description	Default
collections	object	Collection-specific configuration	{}
systemRoles	array	Roles to create/sync on init	[]
excludeCollections	string[]	Collections to exclude from permission system	[]
disablePublicRole	boolean	Disable public access for non-authenticated users	false
publicRolePermissions	string[]	Custom permissions for public users	['*.read']
skipPermissionChecks	boolean | (() => boolean)	Skip permission checks (for seeding/migration)	false
syncRolesOnInit	boolean	Force role sync on every init	false
rolesGroup	string	UI group name for Roles collection	'System'
rolesSlug	string	Custom slug for Roles collection	'roles'

Collection Configuration

Option	Type	Description	Default
enhance	boolean	Add role field to collection	false
roleFieldPlacement	object	Where to place the role field	undefined
autoAssignFirstUser	boolean	Assign super_admin to first user	false
defaultRole	string	Default role for new users	undefined

Utility Functions

checkPermission(payload, userRole, permission, userId?)

Checks if a user has a specific permission. Handles role loading and wildcard matching.

hasPermission(permissions, requiredPermission)

Direct permission check against an array of permissions. Supports wildcards.

canAssignRole(userPermissions, targetRole)

Checks if a user can assign a specific role based on permission subset logic.

Advanced Usage

Collection-Specific Role Visibility

Control which roles appear in the role selection dropdown for each collection:

gatekeeperPlugin({
  collections: {
    'backend-users': {
      enhance: true,
      autoAssignFirstUser: true,  // Makes this an "admin collection"
    },
    'customers': {
      enhance: true,
      defaultRole: 'customer',
    }
  },
  systemRoles: [
    {
      name: 'admin',
      label: 'Administrator',
      permissions: ['users.*'],
      visibleFor: ['backend-users'],  // Only shown for backend-users
    },
    {
      name: 'customer',
      label: 'Customer',
      permissions: ['orders.read'],
      visibleFor: ['customers'],  // Only shown for customers
    },
    {
      name: 'viewer',
      label: 'Read-Only Access',
      permissions: ['*.read'],
      // No visibleFor = shown for all collections
    }
  ]
})

Intelligent Super Admin Visibility: The Super Admin role is automatically set to be visible only for collections with autoAssignFirstUser: true (admin collections). This prevents customers or other non-admin users from seeing or being assigned the Super Admin role.

Custom Collection Name (Compatibility)

If you already have a roles collection in your project, you can configure the plugin to use a different slug:

gatekeeperPlugin({
  rolesSlug: 'admin-roles',  // Use 'admin-roles' instead of 'roles'
  rolesGroup: 'Admin',       // Optional: also change the UI group
  // ... other config
})

Note: When using a custom slug, make sure to update any references in your seed scripts or custom code.

Custom Permissions

You can add custom permissions beyond CRUD operations:

systemRoles: [
  {
    name: 'moderator',
    permissions: [
      'comments.approve',    // Custom permission
      'comments.flag',       // Custom permission
      'users.ban',          // Custom permission
    ]
  }
]

Wrapper Pattern

The plugin wraps existing access control, allowing collections to maintain their own logic:

// Your collection's existing access control still works
const Products: CollectionConfig = {
  access: {
    read: ({ req }) => {
      // Your custom logic here
      return req.user?.company === 'allowed-company'
    }
  }
}

// Plugin adds permission check on top:
// 1. First checks permission (products.read)
// 2. Then checks your custom logic
// Both must pass for access to be granted

Using Environment Variables

The plugin doesn't read environment variables directly. You need to configure them in your plugin options:

// payload.config.ts
gatekeeperPlugin({
  // Use environment variables in your config
  syncRolesOnInit: process.env.SYNC_ROLES === 'true',
  skipPermissionChecks: process.env.SKIP_PERMISSIONS === 'true',
  
  // Or use a function for dynamic control
  skipPermissionChecks: () => process.env.NODE_ENV === 'seed',
})

Then run your application with environment variables:

# Force role synchronization
SYNC_ROLES=true npm run dev

# Skip permissions during seeding
NODE_ENV=seed npm run seed

# Development mode (auto-syncs roles when NODE_ENV=development)
NODE_ENV=development npm run dev

Security Considerations

• First User Setup: The first user in an auth-enabled collection with autoAssignFirstUser: true automatically receives the super_admin role
• Protected Roles: Super admin role is protected by default and cannot be deleted
• Permission Escalation Prevention: Users cannot assign roles with permissions they don't possess
• Wildcard Permissions: Use wildcards carefully - * grants complete system access

Production Deployment

• Initial Setup:

  • Deploy application
  • Start application to create roles (happens automatically on first request)
  • Run seed script to create first admin user

• Role Management:

  • System roles are synced on first start or when none exist
  • In production, roles are not auto-synced unless explicitly configured
  • Manage roles through the admin UI after initial setup

• Backup Considerations:

  • Always backup your roles collection before updates
  • Protected roles provide safety against accidental deletion

TypeScript Support

The plugin is fully typed. Types are automatically generated for your roles and permissions:

import type { Role, Permission } from 'payload-gatekeeper'

// Your role documents will have proper typing
const role: Role = {
  name: 'admin',
  permissions: ['users.*', 'products.read'],
  // ...
}

Testing

# Run all tests
npm test

# Run tests with coverage report
npm run test:coverage

# Run tests in watch mode
npm run test:watch

# Run specific test file
npm test checkUIVisibility

Test Coverage Thresholds

The project maintains high test coverage standards:

Type	Threshold	Current
Lines	80%	90.73% ✅
Branches	80%	85.17% ✅
Functions	80%	82.5% ✅
Statements	80%	90.73% ✅

Development

# Install dependencies
npm install

# Build the plugin
npm run build

# Run linting
npm run lint

# Fix linting issues
npm run lint:fix

# Type checking
npm run typecheck

# Run all quality checks
npm run ci

Project Structure

src/
├── access/           # Access control utilities
├── collections/      # Roles collection definition
├── components/       # React components (role selector)
├── hooks/           # Payload hooks (beforeChange, afterChange, etc.)
├── utils/           # Utility functions
├── types.ts         # TypeScript type definitions
├── constants.ts     # Constants and defaults
├── defaultRoles.ts  # System default roles
└── index.ts         # Main plugin export

CI/CD Integration

GitHub Actions Example

name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '20'
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck
      - run: npm run test:coverage
      - uses: codecov/codecov-action@v3
        with:
          files: ./coverage/lcov.info

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

Development Workflow

• Fork the repository
• Create your feature branch (git checkout -b feature/amazing-feature)
• Write tests for your changes
• Ensure all tests pass (npm test)
• Check coverage (npm run test:coverage)
• Lint your code (npm run lint)
• Commit your changes (git commit -m 'Add amazing feature')
• Push to the branch (git push origin feature/amazing-feature)
• Open a Pull Request

Support

For issues, questions, or suggestions, please open an issue on GitHub.

Acknowledgments

Built with ❤️ for the Payload CMS community.