@nlabs/metropolisjs 0.1.2 → 0.3.0

package/PERMISSION_GRAPHQL_INTEGRATION.md

@@ -0,0 +1,293 @@
+# Permission System GraphQL Integration
+
+This document describes how the MetropolisJS permission system integrates with the Reaktor backend via GraphQL.
+
+## GraphQL Schema
+
+The Reaktor backend should implement the following GraphQL schema for permissions:
+
+### Types
+
+```graphql
+type Permission {
+  permissionId: ID!
+  userId: ID
+  roleId: ID
+  name: String!
+  description: String
+  level: Int!
+  resource: String
+  type: String
+  added: Float
+  updated: Float
+}
+
+input PermissionInput {
+  permissionId: ID
+  userId: ID
+  roleId: ID
+  name: String
+  description: String
+  level: Int!
+  resource: String
+  type: String
+}
+```
+
+### Queries
+
+```graphql
+type Query {
+  permissions: PermissionQueries!
+}
+
+type PermissionQueries {
+  # Check if a user has permission for a resource
+  check(userId: ID!, resource: String!, requiredLevel: Int!): Boolean!
+  
+  # Get a specific permission by ID
+  itemById(permissionId: ID!): Permission
+  
+  # List all permissions with pagination
+  list(from: Int, to: Int): [Permission!]!
+  
+  # List all permissions for a specific user
+  listByUser(userId: ID!): [Permission!]!
+}
+```
+
+### Mutations
+
+```graphql
+type Mutation {
+  permissions: PermissionMutations!
+}
+
+type PermissionMutations {
+  # Grant a new permission
+  add(permission: PermissionInput!): Permission!
+  
+  # Update an existing permission
+  update(permission: PermissionInput!): Permission!
+  
+  # Revoke a permission
+  remove(permissionId: ID!): Permission!
+}
+```
+
+## Implementation Notes
+
+### Permission Levels
+
+The backend should enforce the following permission levels:
+
+- **0** - Guest: Unauthenticated users
+- **1** - User: Authenticated users
+- **2** - Moderator: Content moderators
+- **3** - Admin: Application administrators
+- **4** - Super Admin: System administrators
+
+### Permission Checking
+
+When implementing the `check` query, the backend should:
+
+1. First check if the user has a specific permission for the resource
+2. If no resource-specific permission exists, fall back to the user's `userAccess` level
+3. Return `true` if the user's level is >= the required level
+
+Example backend logic:
+
+```typescript
+async check(userId: string, resource: string, requiredLevel: number): Promise<boolean> {
+  // Check resource-specific permission
+  const permission = await db.permissions.findOne({
+    userId,
+    resource
+  });
+  
+  if (permission) {
+    return permission.level >= requiredLevel;
+  }
+  
+  // Fall back to user's userAccess level
+  const user = await db.users.findOne({ userId });
+  return (user?.userAccess ?? 0) >= requiredLevel;
+}
+```
+
+### Backward Compatibility
+
+The permission system is designed to work with the existing `userAccess` field in the User model:
+
+```graphql
+type User {
+  userId: ID!
+  username: String!
+  userAccess: Int  # 0-4, maps to PermissionLevel
+  # ... other fields
+}
+```
+
+Users without explicit permission records will use their `userAccess` value as their default permission level.
+
+## GraphQL Mutation Examples
+
+### Grant Permission
+
+```graphql
+mutation GrantModeratorPermission {
+  permissions {
+    add(permission: {
+      userId: "user123"
+      name: "Moderator Role"
+      level: 2
+      resource: "posts"
+      description: "Can moderate posts and comments"
+    }) {
+      permissionId
+      name
+      level
+      resource
+      userId
+    }
+  }
+}
+```
+
+### Check Permission
+
+```graphql
+query CheckUserPermission {
+  permissions {
+    check(
+      userId: "user123"
+      resource: "posts"
+      requiredLevel: 2
+    )
+  }
+}
+```
+
+### List User Permissions
+
+```graphql
+query GetUserPermissions {
+  permissions {
+    listByUser(userId: "user123") {
+      permissionId
+      name
+      level
+      resource
+      description
+      added
+      updated
+    }
+  }
+}
+```
+
+### Update Permission
+
+```graphql
+mutation UpdatePermission {
+  permissions {
+    update(permission: {
+      permissionId: "perm123"
+      level: 3
+      description: "Upgraded to admin level"
+    }) {
+      permissionId
+      level
+      description
+    }
+  }
+}
+```
+
+### Revoke Permission
+
+```graphql
+mutation RevokePermission {
+  permissions {
+    remove(permissionId: "perm123") {
+      permissionId
+      name
+    }
+  }
+}
+```
+
+## Database Schema
+
+The backend should store permissions in a collection/table with the following structure:
+
+```typescript
+interface PermissionRecord {
+  _id: string;           // ArangoDB ID
+  _key: string;          // ArangoDB key
+  permissionId: string;  // Unique permission ID
+  userId?: string;       // User this permission is granted to
+  roleId?: string;       // Optional role-based permission
+  name: string;          // Human-readable name
+  description?: string;  // Optional description
+  level: number;         // Permission level (0-4)
+  resource?: string;     // Optional resource scope
+  type?: string;         // Optional type classifier
+  added: number;         // Timestamp when granted
+  updated: number;       // Timestamp when last updated
+}
+```
+
+### Indexes
+
+Recommended indexes for optimal performance:
+
+- `userId` - For quick lookup of user permissions
+- `resource` - For resource-specific queries
+- `level` - For level-based filtering
+- Composite index on `(userId, resource)` - For permission checking
+
+## Security Considerations
+
+1. **Authorization**: Only admins (level >= 3) should be able to grant/revoke permissions
+2. **Validation**: Backend should validate that permission levels are within 0-4 range
+3. **Audit Trail**: Consider logging all permission changes for security auditing
+4. **Resource Validation**: Validate that resource names match expected values
+5. **Self-Service**: Users should not be able to grant themselves higher permissions
+
+## Error Handling
+
+The backend should return appropriate errors:
+
+```graphql
+type PermissionError {
+  code: String!
+  message: String!
+  field: String
+}
+
+# Example error responses
+{
+  "errors": [
+    {
+      "message": "Insufficient permissions to grant admin access",
+      "extensions": {
+        "code": "FORBIDDEN",
+        "field": "level"
+      }
+    }
+  ]
+}
+```
+
+## Testing
+
+The backend should include tests for:
+
+1. Granting permissions to users
+2. Checking permissions with and without resource scope
+3. Listing user permissions
+4. Updating and revoking permissions
+5. Permission inheritance from userAccess field
+6. Authorization checks (only admins can manage permissions)
+7. Edge cases (invalid levels, non-existent users, etc.)

package/PERMISSION_IMPLEMENTATION_SUMMARY.md

@@ -0,0 +1,243 @@
+# Permission System Implementation Summary
+
+## Overview
+
+This document summarizes the complete implementation of the 5-level RBAC (Role-Based Access Control) permission system for MetropolisJS.
+
+## What Was Implemented
+
+### 1. Core Permission Infrastructure
+
+#### Permission Adapter (`src/adapters/permissionAdapter/`)
+- **TypeScript Types**: Complete type definitions for Permission objects
+- **Validation**: Zod schema validation for permission data
+- **Utility Functions**: 
+  - `hasPermission()` - Check if a user level meets requirements
+  - `getPermissionLevelName()` - Get human-readable level names
+  - Level checking helpers: `isGuest()`, `isUser()`, `isModerator()`, `isAdmin()`, `isSuperAdmin()`
+- **Tests**: Comprehensive test suite (100% coverage)
+
+#### Permission Store (`src/stores/permissionStore.ts`)
+- ArkhamJS store for permission state management
+- Handles all CRUD operations (add, get, list, update, remove)
+- Stores user-specific permissions
+- Error handling
+- Comprehensive tests
+
+#### Permission Actions (`src/actions/permissionActions/`)
+- Factory-based action creation following MetropolisJS patterns
+- GraphQL integration for Reaktor backend
+- Methods:
+  - `add()` - Grant permissions
+  - `check()` - Verify user access
+  - `itemById()` - Get specific permission
+  - `list()` - List all permissions
+  - `listByUser()` - Get user's permissions
+  - `remove()` - Revoke permissions
+  - `update()` - Modify permissions
+- Custom adapter support
+- Tests
+
+### 2. React Integration
+
+#### Permission Hooks (`src/utils/permissionUtils.tsx`)
+- **`usePermissions()`**: Main hook for permission checking
+  - Returns current user level
+  - Boolean helpers for level checking
+  - Resource-specific permission checking
+  - Reactive to user state changes
+  
+- **`usePermissionActions()`**: Hook for managing permissions
+  - Created via existing `useMetropolis()` infrastructure
+  - Specialized hook for better performance
+
+#### Permission Guard Component
+- **`<PermissionGuard>`**: Declarative permission-based rendering
+  - Required level specification
+  - Optional resource-specific checking
+  - Fallback content for unauthorized users
+  - Clean, React-friendly API
+
+### 3. Integration with MetropolisJS
+
+- Added permission store to Metropolis initialization
+- Integrated into action factory (`src/utils/actionFactory.ts`)
+- Updated hooks infrastructure (`src/utils/useMetropolis.ts`)
+- Added to MetropolisProvider types (`src/utils/MetropolisProvider.tsx`)
+- Exported all utilities from main package
+
+### 4. Documentation
+
+#### README.md
+- New comprehensive Permission System section
+- Usage examples
+- API documentation
+- Best practices
+- Integration guide
+- Updated "Available Actions" section
+- Updated "Adapters" section
+
+#### Examples
+- `examples/permission-system-usage.tsx`: 10 comprehensive examples covering:
+  - Basic permission checking
+  - Permission Guard usage
+  - Creating and managing permissions
+  - Resource-specific permissions
+  - Listing user permissions
+  - Protected API calls
+  - Permission levels reference
+  - Conditional rendering
+  - Testing permissions
+
+#### GraphQL Integration Guide
+- `PERMISSION_GRAPHQL_INTEGRATION.md`: Complete backend integration guide
+  - GraphQL schema definitions
+  - Query and mutation examples
+  - Implementation notes
+  - Database schema
+  - Security considerations
+  - Testing requirements
+
+## Permission Levels
+
+The system implements 5 hierarchical levels:
+
+| Level | Name | Value | Description |
+|-------|------|-------|-------------|
+| 0 | Guest | `PermissionLevel.GUEST` | Unauthenticated users |
+| 1 | User | `PermissionLevel.USER` | Authenticated users |
+| 2 | Moderator | `PermissionLevel.MODERATOR` | Content moderators |
+| 3 | Admin | `PermissionLevel.ADMIN` | Application admins |
+| 4 | Super Admin | `PermissionLevel.SUPER_ADMIN` | System administrators |
+
+## Backward Compatibility
+
+The system is **100% backward compatible**:
+- Uses existing `userAccess` field (0-4) in User model
+- No breaking changes to existing APIs
+- Graceful fallback to `userAccess` when permissions don't exist
+- All new features are opt-in
+
+## Key Features
+
+1. **Type Safety**: Full TypeScript support throughout
+2. **Validation**: Zod schema validation for data integrity
+3. **Flexibility**: Resource-specific permissions for fine-grained control
+4. **Performance**: Optimized hooks and specialized action creators
+5. **Developer Experience**: Clean, intuitive API with comprehensive docs
+6. **Testing**: Complete test coverage for all components
+7. **Security**: CodeQL scan passed with 0 vulnerabilities
+
+## Usage Example
+
+```tsx
+import { 
+  Metropolis,
+  usePermissions, 
+  usePermissionActions,
+  PermissionGuard, 
+  PermissionLevel 
+} from '@nlabs/metropolisjs';
+
+const App = () => {
+  return (
+    <Metropolis config={{/* config */}}>
+      <Dashboard />
+    </Metropolis>
+  );
+};
+
+const Dashboard = () => {
+  const { isAdmin, userLevel, checkResource } = usePermissions();
+  const permissionActions = usePermissionActions();
+
+  const grantModerator = async (userId: string) => {
+    await permissionActions.add({
+      userId,
+      level: PermissionLevel.MODERATOR,
+      resource: 'posts',
+      name: 'Post Moderator'
+    });
+  };
+
+  return (
+    <div>
+      <h1>Dashboard (Level: {userLevel})</h1>
+      
+      <PermissionGuard 
+        requiredLevel={PermissionLevel.USER}
+        fallback={<p>Please log in</p>}
+      >
+        <UserContent />
+      </PermissionGuard>
+
+      {isAdmin && <AdminPanel />}
+      
+      <PermissionGuard 
+        requiredLevel={PermissionLevel.MODERATOR}
+        resource="posts"
+      >
+        <ModeratePostsButton />
+      </PermissionGuard>
+    </div>
+  );
+};
+```
+
+## Files Created/Modified
+
+### New Files
+- `src/adapters/permissionAdapter/permissionAdapter.ts`
+- `src/adapters/permissionAdapter/permissionAdapter.test.ts`
+- `src/stores/permissionStore.ts`
+- `src/stores/permissionStore.test.ts`
+- `src/actions/permissionActions/permissionActions.ts`
+- `src/actions/permissionActions/permissionActions.test.ts`
+- `src/utils/permissionUtils.tsx`
+- `examples/permission-system-usage.tsx`
+- `PERMISSION_GRAPHQL_INTEGRATION.md`
+- `PERMISSION_IMPLEMENTATION_SUMMARY.md` (this file)
+
+### Modified Files
+- `src/adapters/index.ts` - Export permission adapter
+- `src/stores/index.ts` - Export permission store
+- `src/actions/index.ts` - Export permission actions
+- `src/utils/index.ts` - Export permission utilities
+- `src/utils/actionFactory.ts` - Add permission to action factory
+- `src/utils/useMetropolis.ts` - Add permission hooks
+- `src/utils/MetropolisProvider.tsx` - Add permission adapter type
+- `src/index.tsx` - Add permission store to initialization
+- `README.md` - Add comprehensive permission documentation
+
+## Testing
+
+All components include comprehensive tests:
+- ✅ Permission adapter validation
+- ✅ Permission level checking functions
+- ✅ Permission store state management
+- ✅ Permission actions factory creation
+- ✅ Hook initialization
+
+## Security
+
+- ✅ CodeQL security scan: 0 alerts
+- ✅ Input validation with Zod schemas
+- ✅ Type safety throughout
+- ✅ No hardcoded credentials or secrets
+- ✅ Proper error handling
+
+## Next Steps for Backend Integration
+
+1. Implement GraphQL schema in Reaktor backend (see `PERMISSION_GRAPHQL_INTEGRATION.md`)
+2. Create database collection for permissions
+3. Add authorization middleware for admin-only operations
+4. Implement permission checking logic
+5. Add audit logging for permission changes
+6. Write backend tests
+
+## Notes
+
+- The system is designed to work with both user-level permissions (`userAccess`) and resource-specific permissions
+- Permission checking is hierarchical - higher levels include all lower level permissions
+- Resource-specific permissions override the default `userAccess` level
+- The system is extensible - new permission types and resources can be added without breaking changes