headroom/openspec/changes/headroom-foundation/specs/authentication/spec.md

ADDED 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: 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