[Feature] Build Admin API Endpoints for Protocol Configuration and User Management

[KarenZita01]

Description

The EquipChain platform requires administrative endpoints for managing protocol configuration, user accounts, device registrations, and system parameters. These endpoints must be restricted to authenticated users with the admin role (authentication from Issue #5) and provide a complete CRUD interface for backend administration.

The admin API should include the following endpoint groups: User Management — list all users (GET /api/admin/users), get user details (GET /api/admin/users/:id), create user (POST /api/admin/users), update user roles (PATCH /api/admin/users/:id), deactivate user (DELETE /api/admin/users/:id); Configuration Management — get protocol configuration (GET /api/admin/config), update configuration values (PATCH /api/admin/config), reset to defaults (POST /api/admin/config/reset); Device Management — register device (POST /api/admin/devices), list devices (GET /api/admin/devices), update device metadata (PATCH /api/admin/devices/:id), remove device (DELETE /api/admin/devices/:id); System Monitoring — view system health (GET /api/admin/system/health), view connection pool stats (GET /api/admin/system/stats), view active WebSocket connections (GET /api/admin/system/ws-connections).

All endpoints must follow RESTful conventions, support pagination for list endpoints (leveraging Issue #17), return consistent JSON responses, and include proper error handling. Changes to configuration should be logged with the admin identity and timestamp for audit trail purposes.

Technical Context & Impact

• Dependencies: Depends on auth middleware (Issue [Testing] Expand Test Coverage with Integration Tests, API Tests, and Mock Blockchain Layer #5) for role-based access control. Depends on Zod validation schemas (Issue [Security] Implement Input Validation with Zod Schemas and Request Sanitization #8) for input validation. Should use the repository pattern (Issue [Refactor] Implement Repository Pattern for Clean Data Access Layer Abstraction #22) for data access when available.
• Architecture: New routes under src/routes/admin/ directory with separate files for users.js, config.js, devices.js, system.js. A shared requireAdmin middleware checks req.user.roles includes 'admin'.
• Impact: These endpoints enable platform operators to manage the system without direct database access. This is essential for production operations. The configuration management endpoints allow dynamic protocol parameter updates without code deployments.

Step-by-Step Implementation Guide

1. Create requireAdmin Middleware: Write src/middleware/requireAdmin.js that reads req.user (set by auth middleware from Issue [Testing] Expand Test Coverage with Integration Tests, API Tests, and Mock Blockchain Layer #5), checks for roles containing 'admin', returns 403 if not authorized.
2. Create Admin Routes: Create src/routes/admin/users.js with CRUD operations (initially using in-memory storage, ready for database integration). Create src/routes/admin/config.js with get/update/reset operations for protocol configuration. Create src/routes/admin/devices.js with registration and management endpoints. Create src/routes/admin/system.js with read-only monitoring endpoints.
3. Create Validation Schemas: Write src/schemas/admin.schema.js (if not already done in Issue [Security] Implement Input Validation with Zod Schemas and Request Sanitization #8) with schemas for user creation, config updates, device registration — each with appropriate constraints and required fields.
4. Wire Routes in Application: Update src/index.js to mount admin routes under /api/admin with authenticate and requireAdmin middleware applied to all routes. Ensure proper error handling for database/storage failures.
5. Write Tests: Create tests/unit/admin.test.js testing business logic for user management, config operations. Create tests/integration/admin.test.js testing full request/response cycle with authentication.

Verification & Testing Steps

1. Authenticate as an admin user (using Issue [Testing] Expand Test Coverage with Integration Tests, API Tests, and Mock Blockchain Layer #5 auth flow) to obtain a JWT with admin role.
2. Call GET /api/admin/users with the admin JWT — expect 200 with a list of users (initially empty or seeded).
3. Call POST /api/admin/users with valid user data and admin JWT — expect 201 with the created user object.
4. Call the same endpoints without a JWT — expect 401. Call with a non-admin JWT — expect 403.
5. Call PATCH /api/admin/config with valid configuration changes — expect 200 and verify that subsequent reads reflect the changes.
6. Call DELETE /api/admin/users/:id to deactivate a user — expect 200 and verify the user is marked inactive in subsequent reads.

[Times-stack]

Hi! I'd like to work on this issue.

I have experience building secure Node.js/Express backend APIs with JWT authentication, role-based access control, RESTful design, input validation, and comprehensive automated testing. This issue aligns well with my experience implementing production-ready backend services while keeping the code modular and maintainable.

My approach will be to implement the admin endpoints with a dedicated "requireAdmin" middleware, ensure all routes follow consistent REST conventions, integrate validation using the project's existing schema approach, support pagination where required, and provide clear, consistent error handling. I'll also include audit logging for configuration changes, keep the implementation scoped to the repository requirements, and add thorough unit and integration tests covering authenticated, unauthenticated, authorised, and unauthorised scenarios.

I'll ensure the implementation follows the project's architecture and coding standards, document any important design decisions, and verify that linting, tests, and builds all pass before submitting a clean, reviewer-friendly PR.

I'd appreciate being assigned this issue. Thank you!

[grantfox-oss]

🦊 GrantFox — @Times-stack has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #11)
2. Your PR will be reviewed by the EquipChain maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign | FWC26 campaign!

@Times-stack's PR #33 was approved and merged by @KarenZita01.

🏆 @Times-stack: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (366 total points). Track your full progress on GrantFox.

👏 Great work, @Times-stack! Keep contributing to EquipChain.