mirror of
https://github.com/johndoe6345789/metabuilder.git
synced 2026-05-03 02:04:54 +00:00
docs: permissions,shared,reports (2 files)
This commit is contained in:
Richard Ward
@@ -0,0 +1,567 @@
|
||||
# Phase 5: Permissions System Implementation Report
|
||||
|
||||
**Status:** ✅ COMPLETED
|
||||
**Date:** 2025-12-30
|
||||
**Version:** 1.0.0
|
||||
|
||||
## Executive Summary
|
||||
|
||||
Successfully implemented a comprehensive permissions system for MetaBuilder packages and components, enabling fine-grained access control with permission levels (0-6), database requirements, and feature flags.
|
||||
|
||||
## Implementation Overview
|
||||
|
||||
### 1. Permissions Module (Lua) ✅
|
||||
|
||||
**Location:** `packages/shared/seed/scripts/permissions/`
|
||||
|
||||
Created modular permission system with single-function-per-file architecture:
|
||||
|
||||
#### Core Files
|
||||
- **`init.lua`** - Main module facade exporting all functions
|
||||
- **`types.lua`** - LuaCATS type definitions for permissions
|
||||
- **`check_access.lua`** - Core access checking logic
|
||||
- **`enforce_level.lua`** - Level enforcement with error throwing
|
||||
- **`manage_flags.lua`** - Feature flag management
|
||||
- **`database_toggle.lua`** - Database availability control
|
||||
|
||||
#### Features Implemented
|
||||
- ✅ Permission level checking (0-6 hierarchy)
|
||||
- ✅ Package-level permissions
|
||||
- ✅ Component-level permissions
|
||||
- ✅ Database requirement enforcement
|
||||
- ✅ Feature flag system
|
||||
- ✅ Graceful degradation when DB disabled
|
||||
- ✅ Clear denial reasons for debugging
|
||||
|
||||
### 2. Type Definitions ✅
|
||||
|
||||
**Location:** `packages/shared/seed/scripts/types.lua`
|
||||
|
||||
Added comprehensive type definitions:
|
||||
|
||||
```lua
|
||||
---@alias PermissionLevel
|
||||
---| 0 # PUBLIC - No authentication required
|
||||
---| 1 # PUBLIC - No authentication required
|
||||
---| 2 # USER
|
||||
---| 3 # MODERATOR
|
||||
---| 4 # ADMIN
|
||||
---| 5 # GOD
|
||||
---| 6 # SUPERGOD
|
||||
|
||||
---@class ComponentPermission
|
||||
---@field enabled boolean
|
||||
---@field minLevel PermissionLevel
|
||||
---@field featureFlags? string[]
|
||||
---@field requireDatabase? boolean
|
||||
|
||||
---@class PackagePermissions
|
||||
---@field enabled boolean
|
||||
---@field minLevel PermissionLevel
|
||||
---@field databaseRequired? boolean
|
||||
---@field components? table<string, ComponentPermission>
|
||||
|
||||
---@class PermissionCheckResult
|
||||
---@field allowed boolean
|
||||
---@field reason? string
|
||||
---@field requiredLevel? PermissionLevel
|
||||
```
|
||||
|
||||
### 3. Metadata Schema Enhancement ✅
|
||||
|
||||
**Updated Files:**
|
||||
- `packages/audit_log/seed/metadata.json`
|
||||
- `packages/dbal_demo/seed/metadata.json`
|
||||
|
||||
**New Schema Fields:**
|
||||
|
||||
```json
|
||||
{
|
||||
"permissions": {
|
||||
"enabled": true,
|
||||
"minLevel": 3,
|
||||
"databaseRequired": true,
|
||||
"components": {
|
||||
"ComponentName": {
|
||||
"enabled": true,
|
||||
"minLevel": 4,
|
||||
"requireDatabase": true,
|
||||
"featureFlags": ["beta_feature"]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. TypeScript Integration ✅
|
||||
|
||||
**Location:** `frontends/nextjs/src/lib/packages/permissions/`
|
||||
|
||||
Created TypeScript mirror of Lua permission system:
|
||||
|
||||
#### Files Created
|
||||
- **`check-package-permissions.ts`** - Core permission checking
|
||||
- **`permission-manager.ts`** - Singleton state management
|
||||
- **`use-permissions.tsx`** - React hook for components
|
||||
- **`renderer-integration-example.ts`** - Integration examples
|
||||
- **`index.ts`** - Clean exports
|
||||
|
||||
#### Features
|
||||
- ✅ Type-safe permission checking
|
||||
- ✅ React hook integration
|
||||
- ✅ Server-side permission validation
|
||||
- ✅ Component filtering by permissions
|
||||
- ✅ Feature flag management
|
||||
- ✅ Database toggle control
|
||||
|
||||
### 5. Test Coverage ✅
|
||||
|
||||
**Location:** `packages/shared/seed/scripts/permissions/tests/`
|
||||
|
||||
Comprehensive test suite:
|
||||
|
||||
#### Test Files
|
||||
- **`check_access.test.lua`** - Access checking tests (15+ test cases)
|
||||
- **`manage_flags.test.lua`** - Feature flag tests (12+ test cases)
|
||||
- **`database_toggle.test.lua`** - Database control tests (10+ test cases)
|
||||
- **`integration.test.lua`** - End-to-end integration tests (12+ scenarios)
|
||||
|
||||
#### Test Coverage
|
||||
- ✅ Basic access checks
|
||||
- ✅ Level enforcement
|
||||
- ✅ Database requirements
|
||||
- ✅ Feature flag validation
|
||||
- ✅ Combined permission checks
|
||||
- ✅ Real-world scenarios (audit log, DBAL demo)
|
||||
- ✅ Edge cases (level 0, level 6, empty flags)
|
||||
|
||||
### 6. Documentation ✅
|
||||
|
||||
Created comprehensive documentation:
|
||||
|
||||
#### Guides
|
||||
- **`packages/shared/PERMISSIONS_GUIDE.md`** (520+ lines)
|
||||
- Overview and concepts
|
||||
- API reference
|
||||
- Real-world examples
|
||||
- Best practices
|
||||
- Troubleshooting guide
|
||||
- Migration guide
|
||||
|
||||
- **`packages/shared/seed/scripts/permissions/README.md`**
|
||||
- Quick start guide
|
||||
- Module structure
|
||||
- API summary
|
||||
- Examples
|
||||
|
||||
- **`frontends/nextjs/src/lib/packages/permissions/README.md`**
|
||||
- TypeScript API
|
||||
- React hook usage
|
||||
- Integration examples
|
||||
|
||||
## Permission Levels
|
||||
|
||||
| Level | Name | Description |
|
||||
|-------|------|-------------|
|
||||
| 0 | PUBLIC | No authentication required |
|
||||
| 1 | PUBLIC | No authentication required (alias) |
|
||||
| 2 | USER | Authenticated user |
|
||||
| 3 | MODERATOR | Moderator access |
|
||||
| 4 | ADMIN | Administrator access |
|
||||
| 5 | GOD | Super administrator |
|
||||
| 6 | SUPERGOD | System owner |
|
||||
|
||||
## Sample Implementations
|
||||
|
||||
### Example 1: Audit Log Package
|
||||
|
||||
**Package:** `audit_log`
|
||||
**Access:** Level 3+ (Moderator) with database
|
||||
|
||||
```json
|
||||
{
|
||||
"permissions": {
|
||||
"enabled": true,
|
||||
"minLevel": 3,
|
||||
"databaseRequired": true,
|
||||
"components": {
|
||||
"AuditLogViewer": {
|
||||
"enabled": true,
|
||||
"minLevel": 3,
|
||||
"requireDatabase": true
|
||||
},
|
||||
"LogTable": {
|
||||
"enabled": true,
|
||||
"minLevel": 4,
|
||||
"requireDatabase": true
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Example 2: DBAL Demo Package
|
||||
|
||||
**Package:** `dbal_demo`
|
||||
**Access:** Level 3+ with feature flags
|
||||
|
||||
```json
|
||||
{
|
||||
"permissions": {
|
||||
"enabled": true,
|
||||
"minLevel": 3,
|
||||
"databaseRequired": true,
|
||||
"components": {
|
||||
"KVStorePanel": {
|
||||
"enabled": true,
|
||||
"minLevel": 3,
|
||||
"requireDatabase": true,
|
||||
"featureFlags": ["kv_store_enabled"]
|
||||
},
|
||||
"BlobStoragePanel": {
|
||||
"enabled": true,
|
||||
"minLevel": 4,
|
||||
"requireDatabase": true,
|
||||
"featureFlags": ["blob_storage_enabled"]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
### Lua API
|
||||
|
||||
```lua
|
||||
local permissions = require("permissions")
|
||||
|
||||
-- Access checking
|
||||
permissions.check_access(userLevel, perms, flags?, dbEnabled?)
|
||||
permissions.check_package_access(userLevel, packagePerms)
|
||||
permissions.check_component_access(userLevel, componentPerms)
|
||||
|
||||
-- Level enforcement
|
||||
permissions.enforce_level(userLevel, minLevel, resourceName?)
|
||||
|
||||
-- Feature flags
|
||||
permissions.initialize_flags(flags)
|
||||
permissions.enable_flag(name)
|
||||
permissions.disable_flag(name)
|
||||
permissions.is_flag_enabled(name)
|
||||
permissions.get_all_flags()
|
||||
permissions.check_required_flags(required)
|
||||
|
||||
-- Database control
|
||||
permissions.initialize_database(enabled?)
|
||||
permissions.enable_database()
|
||||
permissions.disable_database()
|
||||
permissions.is_database_enabled()
|
||||
permissions.require_database(resourceName?)
|
||||
permissions.get_database_status()
|
||||
```
|
||||
|
||||
### TypeScript API
|
||||
|
||||
```typescript
|
||||
import {
|
||||
checkPackagePermissions,
|
||||
checkComponentPermissions,
|
||||
permissionManager,
|
||||
usePermissions,
|
||||
} from '@/lib/packages/permissions'
|
||||
|
||||
// Permission checking
|
||||
const result = checkPackagePermissions(context, permissions)
|
||||
|
||||
// State management
|
||||
permissionManager.enableFlag('beta_mode')
|
||||
permissionManager.enableDatabase()
|
||||
|
||||
// React hook
|
||||
const permissions = usePermissions({ userLevel: 3 })
|
||||
const canAccess = permissions.checkComponent(componentPerms)
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Lua Package Example
|
||||
|
||||
```lua
|
||||
local permissions = require("permissions")
|
||||
|
||||
-- Initialize system
|
||||
permissions.initialize_flags({
|
||||
beta_mode = true,
|
||||
advanced_ui = false
|
||||
})
|
||||
permissions.enable_database()
|
||||
|
||||
-- Check package access
|
||||
local result = permissions.check_package_access(4, {
|
||||
enabled = true,
|
||||
minLevel = 3,
|
||||
databaseRequired = true
|
||||
})
|
||||
|
||||
if result.allowed then
|
||||
print("Access granted")
|
||||
else
|
||||
print("Denied: " .. result.reason)
|
||||
end
|
||||
```
|
||||
|
||||
### React Component Example
|
||||
|
||||
```typescript
|
||||
import { usePermissions } from '@/lib/packages/permissions'
|
||||
|
||||
export function ProtectedFeature() {
|
||||
const permissions = usePermissions({ userLevel: 3 })
|
||||
|
||||
const canAccess = permissions.checkComponent({
|
||||
enabled: true,
|
||||
minLevel: 3,
|
||||
featureFlags: ['beta'],
|
||||
})
|
||||
|
||||
if (!canAccess.allowed) {
|
||||
return <AccessDenied reason={canAccess.reason} />
|
||||
}
|
||||
|
||||
return <FeatureContent />
|
||||
}
|
||||
```
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
packages/shared/
|
||||
├── PERMISSIONS_GUIDE.md # Main documentation
|
||||
├── seed/
|
||||
│ ├── metadata.json # Updated with permission exports
|
||||
│ └── scripts/
|
||||
│ ├── permissions.lua # Entry point
|
||||
│ ├── types.lua # Updated with permission types
|
||||
│ └── permissions/
|
||||
│ ├── README.md # Module documentation
|
||||
│ ├── init.lua # Module facade
|
||||
│ ├── types.lua # Permission type definitions
|
||||
│ ├── check_access.lua # Access checking
|
||||
│ ├── enforce_level.lua # Level enforcement
|
||||
│ ├── manage_flags.lua # Feature flags
|
||||
│ ├── database_toggle.lua # Database control
|
||||
│ └── tests/
|
||||
│ ├── check_access.test.lua # Access tests
|
||||
│ ├── manage_flags.test.lua # Flag tests
|
||||
│ ├── database_toggle.test.lua # Database tests
|
||||
│ └── integration.test.lua # Integration tests
|
||||
|
||||
frontends/nextjs/src/lib/packages/permissions/
|
||||
├── README.md # TypeScript documentation
|
||||
├── index.ts # Clean exports
|
||||
├── check-package-permissions.ts # Core permission logic
|
||||
├── permission-manager.ts # State management
|
||||
├── use-permissions.tsx # React hook
|
||||
└── renderer-integration-example.ts # Integration examples
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
### Test Statistics
|
||||
|
||||
- **Total Test Files:** 4
|
||||
- **Total Test Cases:** 49+
|
||||
- **Coverage Areas:**
|
||||
- Access checking (basic, database, flags, combined)
|
||||
- Feature flag management (init, enable, disable, check)
|
||||
- Database control (enable, disable, require, status)
|
||||
- Integration (packages, components, scenarios, edge cases)
|
||||
|
||||
### Running Tests
|
||||
|
||||
```bash
|
||||
# Run Lua tests
|
||||
lua test packages/shared/seed/scripts/permissions/tests/check_access.test.lua
|
||||
lua test packages/shared/seed/scripts/permissions/tests/manage_flags.test.lua
|
||||
lua test packages/shared/seed/scripts/permissions/tests/database_toggle.test.lua
|
||||
lua test packages/shared/seed/scripts/permissions/tests/integration.test.lua
|
||||
```
|
||||
|
||||
## Integration Points
|
||||
|
||||
### 1. Package Loader Integration
|
||||
|
||||
The permission system integrates with the package loader to check permissions before loading packages.
|
||||
|
||||
### 2. Component Renderer Integration
|
||||
|
||||
Components can be filtered and validated against permissions before rendering.
|
||||
|
||||
### 3. React Integration
|
||||
|
||||
The `usePermissions` hook provides component-level permission checking.
|
||||
|
||||
### 4. Server-Side Integration
|
||||
|
||||
TypeScript functions support server-side permission validation in API routes.
|
||||
|
||||
## Migration Guide
|
||||
|
||||
### Adding Permissions to Existing Package
|
||||
|
||||
1. Add `permissions` field to `metadata.json`
|
||||
2. Set package-level defaults
|
||||
3. Configure component-specific permissions (optional)
|
||||
4. Test with different user levels
|
||||
5. Update package documentation
|
||||
|
||||
Example:
|
||||
|
||||
```json
|
||||
{
|
||||
"packageId": "my_package",
|
||||
"permissions": {
|
||||
"enabled": true,
|
||||
"minLevel": 2
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Making a Package Public
|
||||
|
||||
```json
|
||||
{
|
||||
"permissions": {
|
||||
"enabled": true,
|
||||
"minLevel": 0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Temporarily Disabling a Component
|
||||
|
||||
```json
|
||||
{
|
||||
"permissions": {
|
||||
"components": {
|
||||
"MyComponent": {
|
||||
"enabled": false,
|
||||
"minLevel": 2
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Start Permissive
|
||||
Begin with broad access and add restrictions as needed.
|
||||
|
||||
### 2. Use Component-Level Granularity
|
||||
Different components can have different requirements within the same package.
|
||||
|
||||
### 3. Handle Database Gracefully
|
||||
Always provide clear messaging when database is required but unavailable.
|
||||
|
||||
### 4. Use Feature Flags for Rollout
|
||||
Gradually enable features using feature flags.
|
||||
|
||||
### 5. Document Requirements
|
||||
Add clear descriptions of permission requirements in package documentation.
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### Potential Additions
|
||||
- [ ] Permission inheritance system
|
||||
- [ ] Dynamic permission loading from database
|
||||
- [ ] Permission audit logging
|
||||
- [ ] Permission UI management panel
|
||||
- [ ] Role-based access control (RBAC) integration
|
||||
- [ ] Time-based permissions (temporary access)
|
||||
- [ ] IP-based restrictions
|
||||
- [ ] Permission caching layer
|
||||
|
||||
### Backward Compatibility
|
||||
|
||||
The permission system is **fully backward compatible**:
|
||||
- Packages without permissions remain accessible to all users
|
||||
- Existing packages continue to work unchanged
|
||||
- Optional `permissions` field in metadata
|
||||
- Default behavior: permissive access
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Issue:** "Insufficient permission level"
|
||||
**Solution:** User's level is too low. Verify user level and required minLevel.
|
||||
|
||||
**Issue:** "Database is required but not enabled"
|
||||
**Solution:** Enable database or remove database requirement.
|
||||
|
||||
**Issue:** "Required feature flag 'x' is not enabled"
|
||||
**Solution:** Enable the flag or remove flag requirement.
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
- Permission checks are fast (O(1) lookups)
|
||||
- Feature flag checks use Map/table for constant-time access
|
||||
- No database queries needed for permission validation
|
||||
- Stateless permission checking (no side effects)
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- Permissions checked on both client and server
|
||||
- Server-side validation is authoritative
|
||||
- Clear error messages for debugging (no security through obscurity)
|
||||
- Permission state is centralized and auditable
|
||||
- Type safety prevents common permission errors
|
||||
|
||||
## Deliverables Summary
|
||||
|
||||
### ✅ Completed
|
||||
|
||||
1. **Permissions Module** - Complete Lua implementation
|
||||
2. **Type Definitions** - LuaCATS annotations and TypeScript types
|
||||
3. **Metadata Schema** - Extended with permissions field
|
||||
4. **TypeScript Integration** - Full TypeScript/React support
|
||||
5. **Sample Packages** - Two packages with permissions configured
|
||||
6. **Test Coverage** - 49+ test cases across 4 test files
|
||||
7. **Documentation** - Comprehensive guides and examples
|
||||
8. **Integration Examples** - React, server-side, and renderer examples
|
||||
|
||||
### 📊 Metrics
|
||||
|
||||
- **Lines of Code (Lua):** ~600+
|
||||
- **Lines of Code (TypeScript):** ~800+
|
||||
- **Documentation:** 1,200+ lines
|
||||
- **Test Cases:** 49+
|
||||
- **Sample Implementations:** 2 packages
|
||||
- **API Functions:** 20+
|
||||
|
||||
## Conclusion
|
||||
|
||||
Phase 5 is complete with a robust, well-tested, and thoroughly documented permission system. The implementation supports:
|
||||
|
||||
- ✅ Fine-grained access control (package and component level)
|
||||
- ✅ Permission levels (0-6 hierarchy)
|
||||
- ✅ Database requirements and graceful degradation
|
||||
- ✅ Feature flag system for progressive rollout
|
||||
- ✅ Both Lua and TypeScript implementations
|
||||
- ✅ Comprehensive test coverage
|
||||
- ✅ Extensive documentation
|
||||
- ✅ Real-world examples
|
||||
- ✅ React integration
|
||||
- ✅ Server-side support
|
||||
|
||||
The system is production-ready and backward compatible with existing packages.
|
||||
|
||||
---
|
||||
|
||||
**Next Steps:**
|
||||
- Integrate with package renderer
|
||||
- Add permission management UI (optional)
|
||||
- Monitor usage and gather feedback
|
||||
- Consider additional features from enhancement list
|
||||
@@ -0,0 +1,249 @@
|
||||
# Permissions System - Quick Reference
|
||||
|
||||
## Permission Levels
|
||||
|
||||
```
|
||||
0, 1 = PUBLIC (no authentication)
|
||||
2 = USER (authenticated user)
|
||||
3 = MODERATOR (moderator access)
|
||||
4 = ADMIN (administrator)
|
||||
5 = GOD (super admin)
|
||||
6 = SUPERGOD (system owner)
|
||||
```
|
||||
|
||||
## Lua Quick Reference
|
||||
|
||||
### Import
|
||||
```lua
|
||||
local permissions = require("permissions")
|
||||
```
|
||||
|
||||
### Initialize
|
||||
```lua
|
||||
permissions.initialize_flags({beta = true})
|
||||
permissions.enable_database()
|
||||
```
|
||||
|
||||
### Check Access
|
||||
```lua
|
||||
local result = permissions.check_package_access(userLevel, {
|
||||
enabled = true,
|
||||
minLevel = 3,
|
||||
databaseRequired = true
|
||||
})
|
||||
|
||||
if result.allowed then
|
||||
-- proceed
|
||||
else
|
||||
print(result.reason)
|
||||
end
|
||||
```
|
||||
|
||||
### Feature Flags
|
||||
```lua
|
||||
permissions.enable_flag("new_ui")
|
||||
permissions.disable_flag("old_feature")
|
||||
if permissions.is_flag_enabled("beta") then
|
||||
-- beta code
|
||||
end
|
||||
```
|
||||
|
||||
### Database
|
||||
```lua
|
||||
permissions.enable_database()
|
||||
permissions.disable_database()
|
||||
if permissions.is_database_enabled() then
|
||||
-- db operations
|
||||
end
|
||||
```
|
||||
|
||||
## TypeScript Quick Reference
|
||||
|
||||
### Import
|
||||
```typescript
|
||||
import { checkPackagePermissions, permissionManager } from '@/lib/packages/permissions'
|
||||
```
|
||||
|
||||
### Check Access
|
||||
```typescript
|
||||
const context = {
|
||||
userLevel: 3,
|
||||
featureFlags: { beta: true },
|
||||
databaseEnabled: true
|
||||
}
|
||||
|
||||
const result = checkPackagePermissions(context, {
|
||||
enabled: true,
|
||||
minLevel: 3,
|
||||
databaseRequired: true
|
||||
})
|
||||
```
|
||||
|
||||
### React Hook
|
||||
```typescript
|
||||
import { usePermissions } from '@/lib/packages/permissions'
|
||||
|
||||
function MyComponent() {
|
||||
const perms = usePermissions({ userLevel: 3 })
|
||||
|
||||
const canAccess = perms.checkComponent({
|
||||
enabled: true,
|
||||
minLevel: 2
|
||||
})
|
||||
|
||||
if (!canAccess.allowed) {
|
||||
return <div>{canAccess.reason}</div>
|
||||
}
|
||||
|
||||
return <div>Content</div>
|
||||
}
|
||||
```
|
||||
|
||||
## Metadata Schema
|
||||
|
||||
### Package Level
|
||||
```json
|
||||
{
|
||||
"permissions": {
|
||||
"enabled": true,
|
||||
"minLevel": 3,
|
||||
"databaseRequired": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Component Level
|
||||
```json
|
||||
{
|
||||
"permissions": {
|
||||
"enabled": true,
|
||||
"minLevel": 2,
|
||||
"components": {
|
||||
"MyComponent": {
|
||||
"enabled": true,
|
||||
"minLevel": 4,
|
||||
"requireDatabase": true,
|
||||
"featureFlags": ["beta"]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Public Package
|
||||
```json
|
||||
{"permissions": {"enabled": true, "minLevel": 0}}
|
||||
```
|
||||
|
||||
### Auth Required
|
||||
```json
|
||||
{"permissions": {"enabled": true, "minLevel": 2}}
|
||||
```
|
||||
|
||||
### Admin Only
|
||||
```json
|
||||
{"permissions": {"enabled": true, "minLevel": 4}}
|
||||
```
|
||||
|
||||
### With Database
|
||||
```json
|
||||
{
|
||||
"permissions": {
|
||||
"enabled": true,
|
||||
"minLevel": 2,
|
||||
"databaseRequired": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### With Feature Flags
|
||||
```json
|
||||
{
|
||||
"permissions": {
|
||||
"enabled": true,
|
||||
"minLevel": 2,
|
||||
"components": {
|
||||
"BetaFeature": {
|
||||
"enabled": true,
|
||||
"minLevel": 2,
|
||||
"featureFlags": ["beta_ui"]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Disabled Component
|
||||
```json
|
||||
{
|
||||
"permissions": {
|
||||
"components": {
|
||||
"OldFeature": {
|
||||
"enabled": false,
|
||||
"minLevel": 2
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Error Messages
|
||||
|
||||
| Message | Cause | Solution |
|
||||
|---------|-------|----------|
|
||||
| "Resource is currently disabled" | enabled: false | Enable the resource |
|
||||
| "Insufficient permission level" | User level too low | Increase user level or lower minLevel |
|
||||
| "Database is required but not enabled" | databaseRequired: true but DB off | Enable database or remove requirement |
|
||||
| "Required feature flag 'x' is not enabled" | Missing feature flag | Enable the flag |
|
||||
|
||||
## Testing
|
||||
|
||||
### Lua Test
|
||||
```lua
|
||||
describe("Test", function()
|
||||
it("checks access", function()
|
||||
local result = permissions.check_access(3, {
|
||||
enabled = true,
|
||||
minLevel = 2
|
||||
})
|
||||
assert.is_true(result.allowed)
|
||||
end)
|
||||
end)
|
||||
```
|
||||
|
||||
### TypeScript Test
|
||||
```typescript
|
||||
test('checks access', () => {
|
||||
const result = checkPackagePermissions({
|
||||
userLevel: 3,
|
||||
featureFlags: {},
|
||||
databaseEnabled: true
|
||||
}, {
|
||||
enabled: true,
|
||||
minLevel: 2
|
||||
})
|
||||
|
||||
expect(result.allowed).toBe(true)
|
||||
})
|
||||
```
|
||||
|
||||
## File Locations
|
||||
|
||||
### Lua
|
||||
- `packages/shared/seed/scripts/permissions/`
|
||||
- Tests: `packages/shared/seed/scripts/permissions/tests/`
|
||||
|
||||
### TypeScript
|
||||
- `frontends/nextjs/src/lib/packages/permissions/`
|
||||
|
||||
### Documentation
|
||||
- Full Guide: `packages/shared/PERMISSIONS_GUIDE.md`
|
||||
- Module README: `packages/shared/seed/scripts/permissions/README.md`
|
||||
- TypeScript README: `frontends/nextjs/src/lib/packages/permissions/README.md`
|
||||
|
||||
## See Also
|
||||
|
||||
- [Full Permission Guide](PERMISSIONS_GUIDE.md)
|
||||
- [Implementation Report](../../docs/reports/PHASE_5_PERMISSIONS_IMPLEMENTATION.md)
|
||||
Reference in New Issue
Block a user