PIM-Perms UI

React frontend for the PIM-Perms permission management system.

What's in This Repository

This repository contains the frontend implementation:

• pim-perms-ui-core - Base hooks, components, and API client
• pim-perms-ui-rbac - Role & Permission Management pages (8 pages)
• pim-perms-ui-audit - Audit log viewer

Quick Start

Prerequisites

• Node.js 18+
• npm 9+
• pim-perms-api running (backend)

Install & Run

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

# Run tests
npm test

# Run E2E tests
npm run test:e2e

Structure

pim-perms-ui/
├── package.json
├── packages/
│   ├── pim-perms-ui-core/       # Base library
│   │   ├── src/
│   │   │   ├── hooks/           # usePermissions, useSession
│   │   │   ├── components/      # PermissionGate, Layout
│   │   │   └── api/             # API client
│   │   └── __tests__/
│   ├── pim-perms-ui-rbac/       # RBAC management
│   │   ├── src/pages/
│   │   │   ├── UsersPage.tsx
│   │   │   ├── GroupsPage.tsx
│   │   │   ├── RolesPage.tsx
│   │   │   ├── PermissionExplorerPage.tsx
│   │   │   ├── PermissionMatrixPage.tsx
│   │   │   ├── JitAccessPage.tsx
│   │   │   ├── DelegationPage.tsx
│   │   │   └── SettingsPage.tsx
│   │   └── e2e/                 # Playwright tests
│   └── pim-perms-ui-audit/      # Audit viewer
├── test-utils/                   # Shared test utilities
└── e2e/                          # E2E test configuration

Documentation

Central Documentation: pim-perms-docs

UI-Specific:

• UI Architecture
• Implementation Guide
• Component Library
• Testing Strategy

Core Features

Permission Gates

Control UI visibility based on user permissions:

import { PermissionGate } from '@pim-perms/ui-core';

function MyComponent() {
  return (
    <PermissionGate resource="client" action="delete">
      <Button>Delete Client</Button>
    </PermissionGate>
  );
}

Permission Hooks

Check permissions programmatically:

import { usePermissions } from '@pim-perms/ui-core';

function MyComponent() {
  const { can, loading } = usePermissions();
  
  const canDelete = can('client', 'delete');
  
  return <Button disabled={!canDelete}>Delete</Button>;
}

Session Management

Automatic session monitoring:

import { useSession } from '@pim-perms/ui-core';

function App() {
  const { user, expiresIn, extend } = useSession();
  
  // Shows warning at 2 minutes before timeout
  // Auto-logs out on token reuse detection
  // Monitors for MITM attacks
  
  return <YourApp />;
}

RBAC Pages

1. Users Management Page

• DataGrid of all users
• Search/filter by provider, status, role
• User details dialog with 6 tabs:
  • Overview, Direct Roles, Group Memberships, Effective Permissions, Temporary Permissions, Audit Log
• Assign/revoke roles

2. Groups Management Page

• List all groups (LDAP/AD/Local/OAuth)
• Sync from LDAP/AD button
• Group details with 5 tabs
• Assign roles to groups

3. Roles Management Page

• Card/table view of roles
• Create/Edit role wizard
• Permission selector (tree with checkboxes)
• Role details with assignment tracking

4. Permission Explorer

• Tree view of all permissions
• Details panel showing role grants and user assignments
• Search and filter

5. Permission Matrix

• Spreadsheet view: Users × Permissions
• Visual indicators: ✓ (has), ⏰ (temporary), 👥 (inherited)
• Export to CSV/Excel

6. JIT Access Page

• Request temporary permissions
• Approve/deny requests
• View active grants
• Full history

7. Delegation Management

• Create permission delegations
• View delegations I've created/received
• Revoke or extend

8. Settings

• Default roles
• Approval requirements
• LDAP/AD sync configuration
• Audit retention

Testing

Unit Tests (Jest + React Testing Library)

# Run all unit tests
npm test

# Run with coverage
npm run test:coverage

# Watch mode
npm run test:watch

Target: 85%+ coverage

E2E Tests (Playwright)

# Run E2E tests
npm run test:e2e

# Run specific test
npx playwright test users-management

# Debug mode
npx playwright test --debug

Linting

# Check linting
npm run lint

# Auto-fix
npm run lint:fix

# Check types
npm run typecheck

# Format code
npm run format

CI/CD

GitHub Actions automatically:

• ✅ Runs ESLint (fail on warnings)
• ✅ Runs TypeScript type checking
• ✅ Runs unit tests with coverage check (85%+)
• ✅ Runs E2E tests with Playwright
• ✅ Auto-fixes ESLint and Prettier issues (commits back to PR)

Development

Local Development with Backend

# Option 1: Use deployed backend API
VITE_API_URL=https://api.example.com npm run dev

# Option 2: Use local backend
VITE_API_URL=http://localhost:8080 npm run dev

# Option 3: Use mock API (for development without backend)
npm run dev:mock

Adding a New Page

1. Create page component in packages/pim-perms-ui-rbac/src/pages/
2. Add route in router
3. Add permission gates
4. Write unit tests
5. Write E2E test
6. Update documentation

Mock API for Development

Use MSW (Mock Service Worker) for development without backend:

// src/__mocks__/handlers.ts
import { rest } from 'msw';

export const handlers = [
  rest.get('/api/perms/users', (req, res, ctx) => {
    return res(ctx.json({ users: [...] }));
  }),
];

Dependencies

Depends on backend API:

• REST API endpoints from pim-perms-api
• WebSocket for real-time updates

Contributing

1. Create feature branch
2. Implement changes
3. Write tests (maintain 85%+ coverage)
4. Run npm run lint:fix and npm run format
5. Push and create PR
6. CI will auto-fix minor issues
7. Address review comments
8. Merge when approved

Tech Stack

• Framework: React 18 + TypeScript
• State: Zustand + TanStack Query
• UI: Material-UI (MUI) + MUI DataGrid
• Testing: Jest + React Testing Library + Playwright
• Build: Vite
• Linting: ESLint + Prettier

Contact

See main PIM-Perms Documentation for project overview.