Santhosh Janardhanan
f87ccccc4d
address each point.
**Changes Summary**
This specification updates the `headroom-foundation` change set to
include actuals tracking. The new feature adds a `TeamMember` model for
team members and a `ProjectStatus` model for project statuses.
**Summary of Changes**
1. **Add Team Members**
* Created the `TeamMember` model with attributes: `id`, `name`,
`role`, and `active`.
* Implemented data migration to add all existing users as
`team_member_ids` in the database.
2. **Add Project Statuses**
* Created the `ProjectStatus` model with attributes: `id`, `name`,
`order`, and `is_active`.
* Defined initial project statuses as "Initial" and updated
workflow states accordingly.
3. **Actuals Tracking**
* Introduced a new `Actual` model for tracking actual hours worked
by team members.
* Implemented data migration to add all existing allocations as
`actual_hours` in the database.
* Added methods for updating and deleting actual records.
**Open Issues**
1. **Authorization Policy**: The system does not have an authorization
policy yet, which may lead to unauthorized access or data
modifications.
2. **Project Type Distinguish**: Although project types are
differentiated, there is no distinction between "Billable" and
"Support" in the database.
3. **Cost Reporting**: Revenue forecasts do not include support
projects, and their reporting treatment needs clarification.
**Implementation Roadmap**
1. **Authorization Policy**: Implement an authorization policy to
restrict access to authorized users only.
2. **Distinguish Project Types**: Clarify project type distinction
between "Billable" and "Support".
3. **Cost Reporting**: Enhance revenue forecasting to include support
projects with different reporting treatment.
**Task Assignments**
1. **Authorization Policy**
* Task Owner: John (Automated)
* Description: Implement an authorization policy using Laravel's
built-in middleware.
* Deadline: 2026-03-25
2. **Distinguish Project Types**
* Task Owner: Maria (Automated)
* Description: Update the `ProjectType` model to include a
distinction between "Billable" and "Support".
* Deadline: 2026-04-01
3. **Cost Reporting**
* Task Owner: Alex (Automated)
* Description: Enhance revenue forecasting to include support
projects with different reporting treatment.
* Deadline: 2026-04-15
133 lines
5.2 KiB
Markdown
133 lines
5.2 KiB
Markdown
# authentication Specification
|
|
|
|
## Purpose
|
|
TBD - created by archiving change headroom-foundation. Update Purpose after archive.
|
|
## Requirements
|
|
### Requirement: User login
|
|
The system SHALL authenticate users with email and password and issue JWT tokens.
|
|
|
|
#### Scenario: Successful login
|
|
- **WHEN** a user submits valid email "john@example.com" and password
|
|
- **THEN** the system validates the credentials
|
|
- **AND** generates a JWT access token (60 minute TTL)
|
|
- **AND** generates a refresh token (7 day TTL)
|
|
- **AND** returns both tokens along with user details (name, email, role)
|
|
|
|
#### Scenario: Invalid credentials
|
|
- **WHEN** a user submits incorrect email or password
|
|
- **THEN** the system returns 401 Unauthorized error
|
|
- **AND** returns error message "Invalid credentials"
|
|
|
|
#### Scenario: Account locked or inactive
|
|
- **WHEN** a user with inactive account attempts to login
|
|
- **THEN** the system returns 403 Forbidden error
|
|
- **AND** returns error message "Account is inactive"
|
|
|
|
### Requirement: Token-based authentication
|
|
The system SHALL use JWT tokens for authenticating API requests.
|
|
|
|
#### Scenario: Authenticated API request
|
|
- **WHEN** a user sends an API request with valid JWT token in Authorization header
|
|
- **THEN** the system validates the token
|
|
- **AND** extracts user ID and role from token claims
|
|
- **AND** processes the request
|
|
|
|
#### Scenario: Expired token
|
|
- **WHEN** a user sends an API request with expired JWT token
|
|
- **THEN** the system returns 401 Unauthorized error
|
|
- **AND** returns error message "Token expired"
|
|
|
|
#### Scenario: Invalid token
|
|
- **WHEN** a user sends an API request with malformed or tampered JWT token
|
|
- **THEN** the system returns 401 Unauthorized error
|
|
- **AND** returns error message "Invalid token"
|
|
|
|
#### Scenario: Missing token
|
|
- **WHEN** a user sends an API request without Authorization header
|
|
- **THEN** the system returns 401 Unauthorized error
|
|
- **AND** returns error message "Authentication required"
|
|
|
|
### Requirement: Token refresh
|
|
The system SHALL allow users to obtain new access tokens using refresh tokens.
|
|
|
|
#### Scenario: Refresh access token
|
|
- **WHEN** a user submits a valid refresh token to POST /api/auth/refresh
|
|
- **THEN** the system validates the refresh token
|
|
- **AND** generates a new access token (60 minute TTL)
|
|
- **AND** rotates the refresh token (one-time use, issues new refresh token)
|
|
- **AND** returns the new access and refresh tokens
|
|
|
|
#### Scenario: Invalid refresh token
|
|
- **WHEN** a user submits an invalid or expired refresh token
|
|
- **THEN** the system returns 401 Unauthorized error
|
|
- **AND** returns error message "Invalid or expired refresh token"
|
|
|
|
### Requirement: User logout
|
|
The system SHALL allow users to logout and invalidate their tokens.
|
|
|
|
#### Scenario: Successful logout
|
|
- **WHEN** a user sends POST /api/auth/logout with their access token
|
|
- **THEN** the system invalidates the refresh token in Redis
|
|
- **AND** returns success message "Logged out successfully"
|
|
|
|
#### Scenario: Token invalidation
|
|
- **WHEN** a user logs out
|
|
- **THEN** the system removes the refresh token from Redis
|
|
- **AND** subsequent requests with the same tokens are rejected
|
|
|
|
### Requirement: JWT token structure
|
|
The system SHALL include user information in JWT token claims.
|
|
|
|
#### Scenario: Access token claims
|
|
- **WHEN** generating an access token
|
|
- **THEN** the token payload includes:
|
|
- sub (user UUID)
|
|
- role (user role: "superuser", "manager", "developer", "top_brass")
|
|
- permissions (array of permission strings)
|
|
- iat (issued at timestamp)
|
|
- exp (expiration timestamp, 60 minutes from iat)
|
|
- jti (unique token ID)
|
|
|
|
### Requirement: Authenticated user redirect
|
|
The system SHALL redirect authenticated users away from login page to dashboard.
|
|
|
|
#### Scenario: Authenticated user accesses login page
|
|
- **GIVEN** a user has valid access token in localStorage
|
|
- **WHEN** the user navigates to /login
|
|
- **THEN** the system detects the valid token
|
|
- **AND** redirects the user to /dashboard
|
|
- **AND** does not display the login form
|
|
|
|
#### Scenario: Auth state persists after page refresh
|
|
- **GIVEN** a user is logged in with valid tokens
|
|
- **WHEN** the user refreshes the page
|
|
- **THEN** the system reads tokens from localStorage
|
|
- **AND** restores authentication state
|
|
- **AND** displays the authenticated content (not blank page)
|
|
|
|
### Requirement: Refresh token storage
|
|
The system SHALL store refresh tokens in Redis with TTL.
|
|
|
|
#### Scenario: Store refresh token
|
|
- **WHEN** a user logs in
|
|
- **THEN** the system generates a refresh token UUID
|
|
- **AND** stores it in Redis with key "refresh_token:{user_id}:{token_uuid}"
|
|
- **AND** sets TTL to 7 days (10080 minutes)
|
|
|
|
#### Scenario: Validate refresh token
|
|
- **WHEN** a user submits a refresh token
|
|
- **THEN** the system checks if the token exists in Redis
|
|
- **AND** if found and not expired, allows token refresh
|
|
- **AND** if not found or expired, rejects the request
|
|
|
|
### Requirement: Token rotation
|
|
The system SHALL rotate refresh tokens on each refresh request.
|
|
|
|
#### Scenario: Rotate refresh token
|
|
- **WHEN** a user refreshes their access token
|
|
- **THEN** the system invalidates the old refresh token (deletes from Redis)
|
|
- **AND** generates a new refresh token
|
|
- **AND** stores the new refresh token in Redis
|
|
- **AND** returns the new refresh token to the user
|
|
|