88 lines
7.2 KiB
Markdown
88 lines
7.2 KiB
Markdown
# Requirements Document
|
|
|
|
## Introduction
|
|
|
|
The STEAM Security Dashboard currently lacks a self-service user profile. Users cannot view their own account details or change their own password — only admins can reset passwords through the User Management panel. Additionally, the username text in the top-right UserMenu is rendered in black (`text-gray-900`) against the dark dashboard background, making it invisible until hovered. This feature adds a user profile panel accessible from the UserMenu, enables self-service password changes for all authenticated users, and fixes the username visibility issue in the header.
|
|
|
|
## Glossary
|
|
|
|
- **Dashboard**: The STEAM Security Dashboard application, consisting of a React 19 SPA frontend and a Node.js/Express backend with SQLite3 storage.
|
|
- **User_Profile_Panel**: A modal or slide-over panel that displays the authenticated user's account information and provides a password change form.
|
|
- **UserMenu**: The existing dropdown component (`UserMenu.js`) in the top-right corner of the header that shows the user icon, username, group badge, and navigation actions (Manage Users, Audit Log, Sign Out).
|
|
- **Password_Change_Form**: A form within the User_Profile_Panel that accepts the current password and a new password (with confirmation) to allow users to change their own credentials.
|
|
- **Auth_API**: The backend Express routes under `/api/auth` that handle login, logout, session validation, and (with this feature) self-service password changes.
|
|
- **Authenticated_User**: Any user with a valid, non-expired session cookie and an active account.
|
|
- **Header_Username_Display**: The text element in the UserMenu button that shows the current user's username and group label.
|
|
|
|
## Requirements
|
|
|
|
### Requirement 1: User Profile Panel Access
|
|
|
|
**User Story:** As an authenticated user, I want to access a profile panel from the UserMenu dropdown, so that I can view my account details without needing admin assistance.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. WHEN the Authenticated_User clicks the "My Profile" option in the UserMenu dropdown, THE Dashboard SHALL display the User_Profile_Panel.
|
|
2. THE User_Profile_Panel SHALL display the following account fields: username, email address, user group, account creation date, and last login timestamp.
|
|
3. WHEN the User_Profile_Panel is open, THE Dashboard SHALL provide a visible close mechanism (close button or click-outside) to dismiss the panel.
|
|
4. THE User_Profile_Panel SHALL use the dark theme styling defined in the Dashboard design system (intel-card backgrounds, accent borders, light text colors).
|
|
|
|
### Requirement 2: Self-Service Password Change
|
|
|
|
**User Story:** As an authenticated user, I want to change my own password from my profile, so that I can maintain my account security without requesting an admin to reset it.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. THE User_Profile_Panel SHALL include a Password_Change_Form with three fields: current password, new password, and confirm new password.
|
|
2. WHEN the Authenticated_User submits the Password_Change_Form with a valid current password and matching new password fields, THE Auth_API SHALL update the password hash for that user in the database.
|
|
3. WHEN the Authenticated_User submits the Password_Change_Form with an incorrect current password, THE Auth_API SHALL return an error and THE Password_Change_Form SHALL display a message stating the current password is incorrect.
|
|
4. WHEN the new password and confirm new password fields do not match, THE Password_Change_Form SHALL display a validation error before submitting to the Auth_API.
|
|
5. WHEN the new password is fewer than 8 characters, THE Password_Change_Form SHALL display a validation error stating the minimum length requirement.
|
|
6. WHEN a password change succeeds, THE Dashboard SHALL display a success confirmation message and clear the Password_Change_Form fields.
|
|
7. THE Auth_API SHALL hash the new password using bcryptjs before storing it in the database.
|
|
8. WHEN a password change succeeds, THE Auth_API SHALL log an audit entry with action `password_change` for the Authenticated_User.
|
|
|
|
### Requirement 3: Header Username Visibility Fix
|
|
|
|
**User Story:** As a user, I want to see my username in the top-right header area at all times, so that I can confirm which account is logged in without hovering.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. THE Header_Username_Display SHALL render the username text using a light color (design system `--text-primary` or equivalent) that meets WCAG AA contrast ratio against the dark header background.
|
|
2. THE Header_Username_Display SHALL render the group label text using a secondary light color (design system `--text-secondary` or equivalent) that is visible against the dark header background.
|
|
3. THE UserMenu button hover state SHALL use a dark-themed highlight (e.g., `rgba(14, 165, 233, 0.1)`) instead of the current light-themed `hover:bg-gray-100`.
|
|
4. THE UserMenu dropdown chevron icon SHALL use a light color consistent with the header text colors.
|
|
|
|
### Requirement 4: Profile API Endpoint
|
|
|
|
**User Story:** As a frontend developer, I want a dedicated API endpoint that returns the full profile data for the currently authenticated user, so that the User_Profile_Panel can display account details not available in the session payload.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. WHEN the Authenticated_User requests their profile, THE Auth_API SHALL return the user's id, username, email, user group, account creation date, and last login timestamp.
|
|
2. IF an unauthenticated request is made to the profile endpoint, THEN THE Auth_API SHALL return HTTP 401 with an error message.
|
|
3. IF the Authenticated_User's account has been deactivated, THEN THE Auth_API SHALL return HTTP 401 and clear the session cookie.
|
|
|
|
### Requirement 5: Password Change Security
|
|
|
|
**User Story:** As a security-conscious administrator, I want password changes to be rate-limited and validated, so that brute-force attempts against the current password field are mitigated.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. THE Auth_API SHALL enforce a rate limit on the password change endpoint of no more than 5 attempts per 15-minute window per session.
|
|
2. IF the rate limit is exceeded, THEN THE Auth_API SHALL return HTTP 429 with a message indicating the user should try again later.
|
|
3. THE Auth_API SHALL verify that the Authenticated_User's account is active before processing a password change.
|
|
4. THE Auth_API SHALL validate that the new password is at least 8 characters long on the server side.
|
|
|
|
### Requirement 6: UserMenu Dropdown Theming
|
|
|
|
**User Story:** As a user, I want the UserMenu dropdown to match the dark dashboard theme, so that the interface is visually consistent.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. THE UserMenu dropdown panel SHALL use a dark background consistent with the Dashboard design system (intel-card gradient or equivalent dark surface).
|
|
2. THE UserMenu dropdown text items SHALL use light text colors from the design system (`--text-primary` for labels, `--text-secondary` for metadata).
|
|
3. THE UserMenu dropdown hover states SHALL use a subtle accent highlight (e.g., `rgba(14, 165, 233, 0.1)`) instead of the current light-themed `hover:bg-gray-50`.
|
|
4. THE UserMenu dropdown border SHALL use the design system accent border style (`rgba(14, 165, 233, 0.3)` or equivalent).
|
|
5. THE UserMenu group badge in the dropdown header SHALL retain its existing color-coded styling for group identification.
|