docs: add super-admin role documentation
Add comprehensive documentation for the new super-admin role feature: README.md: - Update Users Table schema with isAdmin, isSuperAdmin, lastSeen fields - Add Admin API section with all endpoints - Add User Roles and Permissions section with security rules docs/DOCUMENTATION.md: - Update Users Table schema - Add Admin System section with overview, roles, security rules - Document all admin API endpoints - Add audit logging details - Include JWT token structure - Add setup and deployment instructions CLAUDE.md: - Add Admin System and User Roles section - Document admin service functions - Include security rules - Add JWT token claims structure - Document frontend admin interface Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
@@ -276,6 +276,9 @@ award/
|
||||
callsign: text (not null)
|
||||
lotwUsername: text (nullable)
|
||||
lotwPassword: text (nullable, encrypted)
|
||||
isAdmin: boolean (default: false)
|
||||
isSuperAdmin: boolean (default: false)
|
||||
lastSeen: timestamp (nullable)
|
||||
createdAt: timestamp
|
||||
updatedAt: timestamp
|
||||
}
|
||||
@@ -1034,7 +1037,197 @@ When adding new awards or modifying the award system:
|
||||
|
||||
---
|
||||
|
||||
## Resources
|
||||
## Admin System
|
||||
|
||||
### Overview
|
||||
|
||||
The admin system provides user management, role-based access control, and account impersonation capabilities for support and administrative purposes.
|
||||
|
||||
### User Roles
|
||||
|
||||
The application supports three user roles with increasing permissions:
|
||||
|
||||
#### Regular User
|
||||
- View own QSOs and statistics
|
||||
- Sync from LoTW and DCL
|
||||
- Track award progress
|
||||
- Manage own credentials (LoTW, DCL)
|
||||
|
||||
#### Admin
|
||||
- All user permissions
|
||||
- View system-wide statistics
|
||||
- View all users and their activity
|
||||
- Promote/demote regular users to/from admin role
|
||||
- Delete regular users
|
||||
- Impersonate regular users (for support)
|
||||
- View admin action log
|
||||
|
||||
#### Super Admin
|
||||
- All admin permissions
|
||||
- Promote/demote admins to/from super-admin role
|
||||
- Impersonate other admins (for support)
|
||||
- Cannot be demoted by regular admins
|
||||
- Protected from accidental lockout
|
||||
|
||||
### Security Rules
|
||||
|
||||
**Role Change Restrictions:**
|
||||
- Only super-admins can promote or demote super-admins
|
||||
- Regular admins cannot promote users to super-admin
|
||||
- Super-admins cannot demote themselves
|
||||
- Cannot demote the last super-admin (prevents lockout)
|
||||
|
||||
**Impersonation Restrictions:**
|
||||
- Regular admins can only impersonate regular users
|
||||
- Super-admins can impersonate any user (including other admins)
|
||||
- All impersonation actions are logged to audit trail
|
||||
- Impersonation tokens expire after 1 hour
|
||||
|
||||
### Admin API Endpoints
|
||||
|
||||
**Statistics and Monitoring:**
|
||||
- `GET /api/admin/stats` - System-wide statistics (users, QSOs, jobs)
|
||||
- `GET /api/admin/users` - List all users with statistics
|
||||
- `GET /api/admin/users/:userId` - Get detailed user information
|
||||
- `GET /api/admin/actions` - View admin action log
|
||||
- `GET /api/admin/actions/my` - View current admin's actions
|
||||
|
||||
**User Management:**
|
||||
- `POST /api/admin/users/:userId/role` - Change user role
|
||||
- Body: `{ "role": "user" | "admin" | "super-admin" }`
|
||||
- `DELETE /api/admin/users/:userId` - Delete a user
|
||||
|
||||
**Impersonation:**
|
||||
- `POST /api/admin/impersonate/:userId` - Start impersonating a user
|
||||
- `POST /api/admin/impersonate/stop` - Stop impersonation
|
||||
- `GET /api/admin/impersonation/status` - Check impersonation status
|
||||
|
||||
### Admin Service
|
||||
|
||||
**File:** `src/backend/services/admin.service.js`
|
||||
|
||||
**Key Functions:**
|
||||
|
||||
```javascript
|
||||
// Check user permissions
|
||||
await isAdmin(userId)
|
||||
await isSuperAdmin(userId)
|
||||
|
||||
// Role management
|
||||
await changeUserRole(adminId, targetUserId, newRole)
|
||||
|
||||
// Impersonation
|
||||
await impersonateUser(adminId, targetUserId)
|
||||
await verifyImpersonation(impersonationToken)
|
||||
await stopImpersonation(adminId, targetUserId)
|
||||
|
||||
// Audit logging
|
||||
await logAdminAction(adminId, actionType, targetUserId, details)
|
||||
```
|
||||
|
||||
### Audit Logging
|
||||
|
||||
All admin actions are logged to the `admin_actions` table for audit purposes:
|
||||
|
||||
**Action Types:**
|
||||
- `impersonate_start` - Started impersonating a user
|
||||
- `impersonate_stop` - Stopped impersonation
|
||||
- `role_change` - Changed user role
|
||||
- `user_delete` - Deleted a user
|
||||
|
||||
**Log Entry Structure:**
|
||||
```javascript
|
||||
{
|
||||
id: integer,
|
||||
adminId: integer,
|
||||
actionType: string,
|
||||
targetUserId: integer (nullable),
|
||||
details: string (JSON),
|
||||
createdAt: timestamp
|
||||
}
|
||||
```
|
||||
|
||||
### Frontend Admin Interface
|
||||
|
||||
**Route:** `/admin` (admin only)
|
||||
|
||||
**Features:**
|
||||
- **Overview Tab:** System statistics dashboard
|
||||
- **Users Tab:** User management with filtering
|
||||
- **Awards Tab:** Award definition management
|
||||
- **Action Log Tab:** Audit trail of admin actions
|
||||
|
||||
**User Management Actions:**
|
||||
- **Impersonate** - Switch to user account (disabled for admins unless super-admin)
|
||||
- **Promote/Demote** - Change user role
|
||||
- **Delete** - Remove user and all associated data
|
||||
|
||||
### JWT Token Claims
|
||||
|
||||
Admin tokens include additional claims:
|
||||
|
||||
```javascript
|
||||
{
|
||||
userId: number,
|
||||
email: string,
|
||||
callsign: string,
|
||||
isAdmin: boolean,
|
||||
isSuperAdmin: boolean, // New: Super-admin flag
|
||||
exp: number
|
||||
}
|
||||
```
|
||||
|
||||
**Impersonation Token:**
|
||||
```javascript
|
||||
{
|
||||
userId: number, // Target user ID
|
||||
email: string,
|
||||
callsign: string,
|
||||
isAdmin: boolean,
|
||||
isSuperAdmin: boolean,
|
||||
impersonatedBy: number, // Admin ID who started impersonation
|
||||
exp: number // 1 hour expiration
|
||||
}
|
||||
```
|
||||
|
||||
### Setup
|
||||
|
||||
**To create the first super-admin:**
|
||||
|
||||
1. Register a user account normally
|
||||
2. Access the database directly:
|
||||
```bash
|
||||
sqlite3 src/backend/award.db
|
||||
```
|
||||
|
||||
3. Update the user to super-admin:
|
||||
```sql
|
||||
UPDATE users SET is_super_admin = 1 WHERE email = 'your@email.com';
|
||||
```
|
||||
|
||||
4. Log out and log back in to get the updated JWT token
|
||||
|
||||
**To promote users via the admin interface:**
|
||||
1. Log in as a super-admin
|
||||
2. Navigate to `/admin`
|
||||
3. Find the user in the Users tab
|
||||
4. Click "Promote" and select "Super Admin"
|
||||
|
||||
### Production Deployment
|
||||
|
||||
After pulling the latest code:
|
||||
|
||||
```bash
|
||||
# Apply database migration (adds is_super_admin column)
|
||||
sqlite3 src/backend/award.db "ALTER TABLE users ADD COLUMN is_super_admin INTEGER DEFAULT 0 NOT NULL;"
|
||||
|
||||
# Restart backend
|
||||
pm2 restart award-backend
|
||||
|
||||
# Promote a user to super-admin via database or existing admin interface
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
- [ARRL LoTW](https://lotw.arrl.org/)
|
||||
- [DARC Community Logbook (DCL)](https://dcl.darc.de/)
|
||||
|
||||
Reference in New Issue
Block a user