Headroom - Foundation

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

@@ -0,0 +1,111 @@
+## 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