Merge pull request #1 from sSeewald/feature/public-access

Add public role feature

Author: sSeewald

README.md

@@ -30,6 +30,22 @@ A comprehensive, production-ready permissions system with role-based access cont
 - ⚡ **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
+![Roles Collection](docs/roles-collection-with-default-roles.png)
+*The Roles collection showing system default roles - fully manageable through the UI*
+
+### User Role Assignment
+![User Creation with Role Selection](docs/users-collection-create-new-user-select-roles.png)
+*Assigning roles when creating new users - with searchable dropdown*
+
+### Users with Roles
+![Users Collection with Roles](docs/users-collection-with-roles.png)
+*Users overview showing their assigned roles*
+
 ## Installation
 
 ```bash
@@ -55,13 +71,22 @@ export default buildConfig({
       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:
+
+![First User Creation](docs/create-first-user.png)
+*The first user gets super admin privileges automatically*
+
 ## Configuration
 
 ### Full Configuration Example
@@ -143,11 +168,8 @@ export default buildConfig({
       // Optional: Exclude collections from permission system
       excludeCollections: ['public-pages'],
 
-      // Optional: Enable audit logging
-      enableAuditLog: false,
-      
       // Environment-based options
-      seedingMode: false,  // Set to true during seeding
+      skipPermissionChecks: false,  // Set to true during seeding/migration
       syncRolesOnInit: process.env.SYNC_ROLES === 'true',
 
       // UI customization
@@ -160,6 +182,41 @@ export default buildConfig({
 
 ## Core Concepts
 
+### Public Access
+
+Non-authenticated users automatically have configurable public access:
+
+```typescript
+// 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 Editor Role](docs/roles-collection-create-new-role-editor.png)
+*Creating a new editor role with specific permissions*
+
+![Roles with Custom Editor](docs/roles-collection-with-custom-role-editor.png)
+*Roles collection showing both system and custom roles*
+
 ### Permission Patterns
 
 The plugin supports various permission patterns:
@@ -175,13 +232,16 @@ The plugin supports various permission patterns:
 Protected roles cannot be deleted and have restricted field updates. Only users with `*` permission can modify protected roles.
 
 ```typescript
-{
+const superAdminRole = {
   name: 'super_admin',
   permissions: ['*'],
   protected: true,  // Cannot be deleted, limited updates
 }
 ```
 
+![Super Admin Role Details](docs/role-details-super-admin.png)
+*Protected super admin role showing the lock indicator and full permissions*
+
 ### UI Visibility vs CRUD Operations
 
 The plugin separates UI visibility from CRUD operations:
@@ -405,14 +465,18 @@ gatekeeperPlugin({
 })
 ```
 
-### Seeding First Admin User
+### 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:
 
 ```typescript
 // seed-admin.ts
 import { getPayload } from 'payload'
 import config from './payload.config'
 
-async function seedAdmin() {
+async function seedFirstAdmin() {
   const payload = await getPayload({ config })
 
   try {
@@ -426,38 +490,81 @@ async function seedAdmin() {
       return
     }
 
-    // Find the super_admin role (created by plugin on first start)
-    const superAdminRole = await payload.find({
-      collection: 'roles',
-      where: {
-        name: { equals: 'super_admin' },
-      },
-    })
-
-    if (superAdminRole.docs.length === 0) {
-      throw new Error('Super admin role not found! Start the application first.')
-    }
-
-    // Create the first admin user
+    // Create the first admin user - automatically gets super_admin role!
     await payload.create({
       collection: 'users',
       data: {
         email: 'admin@example.com',
         password: 'SecurePassword123!',
-        role: superAdminRole.docs[0].id,
-        // ... other fields
+        // No need to set role - autoAssignFirstUser handles it
       },
     })
 
-    console.log('✅ Admin user created successfully')
+    console.log('✅ First admin user created with super_admin role')
   } catch (error) {
     console.error('Error seeding admin:', error)
   }
 
   process.exit(0)
 }
 
-seedAdmin()
+seedFirstAdmin()
+```
+
+#### Advanced: Multiple Users with Specific Roles
+
+Only search for roles when you need to create additional users with specific roles:
+
+```typescript
+// 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: 'editor@example.com',
+          password: 'EditorPass123!',
+          role: editorRole.docs[0].id,
+        },
+      })
+    }
+
+    // Create viewer user
+    if (viewerRole.docs.length > 0) {
+      await payload.create({
+        collection: 'users',
+        data: {
+          email: 'viewer@example.com',
+          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
@@ -494,8 +601,9 @@ async function myCustomEndpoint(req: PayloadRequest) {
 | `collections` | `object` | Collection-specific configuration | `{}` |
 | `systemRoles` | `array` | Roles to create/sync on init | `[]` |
 | `excludeCollections` | `string[]` | Collections to exclude from permission system | `[]` |
-| `enableAuditLog` | `boolean` | Enable audit logging | `false` |
-| `seedingMode` | `boolean` | Skip permission checks during seeding | `false` |
+| `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'` |
@@ -615,16 +723,32 @@ const Products: CollectionConfig = {
 // Both must pass for access to be granted
 ```
 
-### Environment Variables
+### Using Environment Variables
 
-```bash
-# Skip permission checks during seeding (configure in plugin options)
-npm run seed
+The plugin doesn't read environment variables directly. You need to configure them in your plugin options:
+
+```typescript
+// 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:
+
+```bash
 # Force role synchronization
 SYNC_ROLES=true npm run dev
 
-# Development mode (auto-syncs roles)
+# 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
 ```
 
@@ -668,8 +792,6 @@ const role: Role = {
 
 ## Testing
 
-The plugin has comprehensive test coverage with a blackbox testing approach:
-
 ```bash
 # Run all tests
 npm test
@@ -782,16 +904,6 @@ Contributions are welcome! Please read our contributing guidelines before submit
 
 For issues, questions, or suggestions, please open an issue on GitHub.
 
-## Roadmap
-
-- [ ] Global permissions UI component
-- [ ] Audit log persistence
-- [ ] Permission templates
-- [ ] Dynamic permission generation from custom fields
-- [ ] GraphQL support
-- [ ] Permission caching layer
-- [ ] Role hierarchy support
-
 ## Acknowledgments
 
 Built with ❤️ for the [Payload CMS](https://payloadcms.com/) community.

docs/create-first-user.png

@@ -6,4 +6,29 @@ global.console = {
   warn: jest.fn(),
   error: jest.fn(),
   debug: jest.fn(),
-}
+}
+
+// Mock Payload module and its error classes
+jest.mock('payload', () => {
+  // Create mock error classes that match Payload's error structure
+  class ValidationError extends Error {
+    constructor(options) {
+      super(options.errors?.[0]?.message || 'Validation error')
+      this.name = 'ValidationError'
+      this.errors = options.errors || []
+      this.collection = options.collection
+    }
+  }
+
+  class Forbidden extends Error {
+    constructor(message) {
+      super(message || 'Forbidden')
+      this.name = 'Forbidden'
+    }
+  }
+
+  return {
+    ValidationError,
+    Forbidden,
+  }
+})

docs/role-details-super-admin.png

@@ -3,18 +3,18 @@
   "version": "1.0.0",
   "description": "The ultimate access control gatekeeper for Payload CMS v3 - Advanced RBAC with wildcard support, auto role assignment, and flexible configuration",
   "type": "module",
-  "main": "dist/cjs/index.cjs",
+  "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
   "types": "dist/esm/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/esm/index.d.ts",
       "import": "./dist/esm/index.js",
-      "require": "./dist/cjs/index.cjs"
+      "require": "./dist/cjs/index.js"
     },
     "./components/*": {
       "import": "./dist/esm/components/*.js",
-      "require": "./dist/cjs/components/*.cjs"
+      "require": "./dist/cjs/components/*.js"
     },
     "./package.json": "./package.json"
   },