cve-dashboard/.kiro/specs/group-based-access-control/requirements.md

Requirements Document

Introduction

Replace the existing simple role-based access control system (admin/editor/viewer) with a group-based access control model. The system supports exactly four user groups (Admin, Standard User, Leadership, Read Only) with distinct permission boundaries. This change affects the database schema, backend middleware, API endpoint authorization, frontend conditional rendering, and the admin panel user management interface.

Glossary

• Dashboard: The STEAM Security Dashboard application comprising a React frontend and Express backend
• Group: One of four access control categories (Admin, Standard_User, Leadership, Read_Only) that determines a user's permissions
• Admin_Group: The group with full CRUD access to all resources, user management, and admin panel access
• Standard_User_Group: The working group with view-all, create, edit, and conditional delete permissions plus basic export
• Leadership_Group: The read-only group with additional export capabilities for reports, compliance documents, and visualizations
• Read_Only_Group: The view-only group with no create, edit, delete, or export capabilities
• Permission_Middleware: Backend Express middleware that validates a user's group membership before allowing an API action
• Cascade_Impact: The set of associated Archer tickets, JIRA tickets, and documents that would be deleted when a CVE is deleted
• Compliance_Link: An association between a ticket (Archer or JIRA) and a compliance report that blocks Standard_User deletion
• Group_Migration: The database migration that replaces the role field with a group field and maps existing users

Requirements

Requirement 1: Group Data Model

User Story: As a system administrator, I want the user model to reference one of four defined groups instead of the legacy role field, so that permissions are enforced through a well-defined group structure.

Acceptance Criteria

1. THE Dashboard SHALL store exactly four groups: Admin, Standard_User, Leadership, and Read_Only
2. THE Dashboard SHALL assign each user to exactly one group via a group field on the user record
3. WHEN a user record is created, THE Dashboard SHALL default the group to Read_Only
4. THE Dashboard SHALL enforce a foreign key or CHECK constraint so that the group field only accepts valid group values

Requirement 2: Group Migration

User Story: As a system administrator, I want existing users to be automatically mapped from the old role system to the new group system, so that no manual re-assignment is needed after the upgrade.

Acceptance Criteria

1. WHEN the migration runs, THE Group_Migration SHALL map users with role "admin" to Admin_Group
2. WHEN the migration runs, THE Group_Migration SHALL map users with role "editor" to Standard_User_Group
3. WHEN the migration runs, THE Group_Migration SHALL map users with role "viewer" to Read_Only_Group
4. WHEN the migration runs, THE Group_Migration SHALL remove the CHECK constraint on the old role column and replace it with the new group field
5. IF a user record has no role value or an unrecognized role value, THEN THE Group_Migration SHALL assign that user to Read_Only_Group

Requirement 3: Backend Permission Enforcement

User Story: As a security-conscious developer, I want every API endpoint to check the requesting user's group before allowing the action, so that permissions are enforced server-side and cannot be bypassed through direct API calls.

Acceptance Criteria

1. THE Permission_Middleware SHALL replace the existing requireRole middleware with a requireGroup middleware that accepts one or more group names
2. WHEN an unauthenticated request reaches a protected endpoint, THE Permission_Middleware SHALL return HTTP 401
3. WHEN an authenticated user's group is not in the allowed groups for an endpoint, THE Permission_Middleware SHALL return HTTP 403
4. THE Permission_Middleware SHALL attach the user's group to the request object for downstream route handlers to use
5. WHEN a Standard_User_Group user attempts to delete a resource they did not create, THE Dashboard SHALL return HTTP 403
6. WHEN a Standard_User_Group user attempts to delete a finding that is marked as resolved or closed, THE Dashboard SHALL return HTTP 403
7. WHEN a Standard_User_Group user attempts to delete a ticket that is linked to a compliance report, THE Dashboard SHALL return HTTP 403
8. WHEN a Standard_User_Group user attempts to delete a CVE they created, THE Dashboard SHALL check for Cascade_Impact and return the list of associated Archer tickets, JIRA tickets, and documents
9. IF any ticket in the Cascade_Impact is linked to a compliance report, THEN THE Dashboard SHALL block the CVE deletion and return HTTP 403 with a message indicating Admin-only deletion is required
10. WHEN an Admin_Group user performs any CRUD operation, THE Dashboard SHALL allow the operation without ownership or state restrictions

Requirement 4: Admin Group Permissions

User Story: As an admin, I want full unrestricted access to all resources and management functions, so that I can manage the entire system without limitations.

Acceptance Criteria

1. THE Dashboard SHALL allow Admin_Group users to create, read, update, and delete all resources (CVEs, findings, tickets, comments, compliance reports)
2. THE Dashboard SHALL allow Admin_Group users to access the admin panel
3. THE Dashboard SHALL allow Admin_Group users to manage users and assign users to groups
4. THE Dashboard SHALL allow Admin_Group users to export all data
5. THE Dashboard SHALL allow Admin_Group users to delete any resource regardless of ownership, state, or compliance linkage

Requirement 5: Standard User Group Permissions

User Story: As a standard user, I want to view all data and create/edit resources while having controlled delete access, so that I can do my daily work without accidentally removing critical linked data.

Acceptance Criteria

1. THE Dashboard SHALL allow Standard_User_Group users to view all data across the dashboard
2. THE Dashboard SHALL allow Standard_User_Group users to create and edit CVEs, findings, tickets, and comments
3. THE Dashboard SHALL allow Standard_User_Group users to delete their own findings, tickets, and comments subject to state and linkage restrictions
4. WHEN a Standard_User_Group user attempts to delete a finding that is resolved or closed, THE Dashboard SHALL reject the deletion
5. WHEN a Standard_User_Group user attempts to delete a ticket linked to a compliance report, THE Dashboard SHALL reject the deletion
6. WHEN a Standard_User_Group user attempts to delete a CVE they created, THE Dashboard SHALL display a warning listing associated Archer tickets, JIRA tickets, and documents that will be cascade-deleted
7. IF any associated ticket in the cascade is linked to a compliance report, THEN THE Dashboard SHALL block the CVE deletion entirely
8. THE Dashboard SHALL allow Standard_User_Group users to perform basic exports (CSV and XLSX of CVEs and findings)

Requirement 6: Leadership Group Permissions

User Story: As a leadership user, I want read-only access with export capabilities, so that I can review data and generate reports without risk of modifying records.

Acceptance Criteria

1. THE Dashboard SHALL allow Leadership_Group users to view all data across the dashboard
2. THE Dashboard SHALL allow Leadership_Group users to export reports, compliance documents, and graph visualizations
3. THE Dashboard SHALL prevent Leadership_Group users from creating, editing, or deleting any records
4. THE Dashboard SHALL prevent Leadership_Group users from accessing the admin panel

Requirement 7: Read Only Group Permissions

User Story: As a read-only user, I want view-only access to the dashboard, so that I can see data without any ability to modify or export it.

Acceptance Criteria

1. THE Dashboard SHALL allow Read_Only_Group users to view all data across the dashboard
2. THE Dashboard SHALL prevent Read_Only_Group users from creating, editing, or deleting any records
3. THE Dashboard SHALL prevent Read_Only_Group users from exporting any data
4. THE Dashboard SHALL prevent Read_Only_Group users from accessing the admin panel

Requirement 8: Admin Panel Group Management

User Story: As an admin, I want to view all users with their current group and reassign groups through the admin panel, so that I can manage access control centrally.

Acceptance Criteria

1. WHEN an Admin_Group user opens the user management section, THE Dashboard SHALL display all users with their current group assignment
2. WHEN an Admin_Group user changes a user's group, THE Dashboard SHALL update the group assignment and persist it to the database
3. WHEN an Admin_Group user changes a user's group, THE Dashboard SHALL display a confirmation dialog before applying the change
4. WHEN an Admin_Group user downgrades another Admin_Group user, THE Dashboard SHALL display an additional warning in the confirmation dialog
5. THE Dashboard SHALL prevent an Admin_Group user from changing their own group to a non-Admin group

Requirement 9: Audit Logging for Group Changes

User Story: As a system administrator, I want all group assignment changes to be logged with full context, so that I can audit who changed access for whom and when.

Acceptance Criteria

1. WHEN a user's group is changed, THE Dashboard SHALL log the change with the acting user's ID, the target user's ID, the previous group, the new group, and a timestamp
2. THE Dashboard SHALL preserve existing audit trail behavior for all CRUD operations performed under the new group system
3. WHEN a group change is logged, THE Dashboard SHALL record the IP address of the acting user

Requirement 10: Frontend Conditional Rendering

User Story: As a user, I want the UI to show only the actions available to my group, so that I have a clear and uncluttered interface matching my permissions.

Acceptance Criteria

1. THE Dashboard SHALL conditionally render create, edit, and delete buttons based on the current user's group
2. THE Dashboard SHALL conditionally render export options based on the current user's group
3. THE Dashboard SHALL conditionally render the admin panel link based on the current user's group
4. WHEN a Standard_User_Group user views a resource they did not create, THE Dashboard SHALL hide the delete button for that resource
5. THE Dashboard SHALL replace the existing role-based helper functions (hasRole, canWrite, isAdmin) with group-based equivalents (isInGroup, canWrite, canDelete, canExport, isAdmin)