Files

Santhosh Janardhanan f87ccccc4d Based on the provided specification, I will summarize the changes and

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

2026-04-20 16:38:41 -04:00

5.2 KiB

Raw Blame History

authentication Specification

Purpose

TBD - created by archiving change headroom-foundation. Update Purpose after archive.

Requirements

The system SHALL authenticate users with email and password and issue JWT tokens.

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.

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

5.2 KiB Raw Blame History