Task_Reporter/openspec/specs/authentication/spec.md

authentication Specification

Purpose

TBD - created by archiving change add-user-authentication. Update Purpose after archive.

Requirements

Requirement: User Login with Dual-Token Session Management

The system SHALL authenticate users by forwarding credentials to the Panjit AD authentication API (https://pj-auth-api.vercel.app/api/auth/login). Upon successful AD authentication, the system SHALL generate its own internal session token (separate from the AD token), encrypt the user's password using AES-256 encryption (for auto-refresh capability), and store all session data in the database. The internal token is returned to the client for subsequent requests.

Scenario: Successful login with valid credentials

• WHEN a user submits username "ymirliu@panjit.com.tw" and password "4RFV5tgb6yhn" to POST /api/auth/login
• THEN the system SHALL forward the credentials to the AD API
• AND receive a 200 response with token and username fields
• AND encrypt the password using Fernet symmetric encryption (AES-256)
• AND generate a unique internal session token (UUID4)
• AND estimate or record the AD token expiry time (e.g., current_time + 1 hour)
• AND create a session record in the user_sessions table with: username, display_name (from AD), internal_token, ad_token, encrypted_password, ad_token_expires_at, refresh_attempt_count (default 0), last_activity (current time), created_at
• AND return status 200 with JSON body {"token": "<internal_token>", "display_name": "<username>"}

Scenario: Password stored securely with encryption

• WHEN a password is stored in the user_sessions table
• THEN the system SHALL encrypt it using the Fernet encryption key from environment variable FERNET_KEY
• AND the encrypted_password field SHALL contain ciphertext that differs from the plaintext
• AND decrypting the ciphertext SHALL reproduce the original password exactly

Scenario: Failed login with invalid credentials

• WHEN a user submits incorrect username or password to POST /api/auth/login
• THEN the system SHALL forward the credentials to the AD API
• AND receive a non-200 response (e.g., 401 Unauthorized)
• AND return status 401 to the client with error message {"error": "Invalid credentials"}
• AND NOT create any session record in the database

Scenario: AD API service unavailable

• WHEN a user attempts to login but the AD API (https://pj-auth-api.vercel.app) is unreachable
• THEN the system SHALL return status 503 with error message {"error": "Authentication service unavailable"}

Requirement: User Logout

The system SHALL provide a logout endpoint that deletes the user's session record from the database.

Scenario: Successful logout with valid internal token

• WHEN an authenticated user sends POST /api/auth/logout with header Authorization: Bearer <valid_internal_token>
• THEN the system SHALL delete the session record from the user_sessions table
• AND return status 200 with {"message": "Logout successful"}

Scenario: Logout without authentication token

• WHEN a user sends POST /api/auth/logout without the Authorization header
• THEN the system SHALL return status 401 with {"error": "No authentication token provided"}

Requirement: Automatic AD Token Refresh with Retry Limit

The system SHALL automatically refresh the AD token before it expires (within 5 minutes of expiry) when the user makes any API request, using the encrypted password stored in the database. The system SHALL limit auto-refresh attempts to a maximum of 3 consecutive failures, after which the session is forcibly terminated (to handle cases where the AD password has been changed).

Scenario: Auto-refresh AD token on protected route access

• WHEN an authenticated user accesses a protected endpoint with a valid internal_token
• AND the stored ad_token will expire in less than 5 minutes (ad_token_expires_at - now < 5 minutes)
• AND refresh_attempt_count is less than 3
• THEN the system SHALL decrypt the encrypted_password from the database
• AND re-authenticate with the AD API using the decrypted password
• AND if authentication succeeds: update ad_token, ad_token_expires_at, reset refresh_attempt_count to 0
• AND update the last_activity timestamp
• AND allow the request to proceed normally

Scenario: No refresh needed for fresh AD token

• WHEN an authenticated user accesses a protected endpoint with a valid internal_token
• AND the stored ad_token will not expire within 5 minutes
• THEN the system SHALL NOT call the AD API
• AND update only the last_activity timestamp
• AND allow the request to proceed

Scenario: Auto-refresh fails but retry limit not reached

• WHEN an authenticated user accesses a protected endpoint triggering auto-refresh
• AND the AD API returns 401 (password invalid or changed)
• AND refresh_attempt_count is 0, 1, or 2
• THEN the system SHALL increment refresh_attempt_count by 1
• AND log the failed refresh attempt with timestamp for audit
• AND return status 401 with {"error": "Token refresh failed. Please try again or re-login if issue persists."}
• AND keep the session record in the database

Scenario: Auto-refresh fails 3 consecutive times - force logout

• WHEN an authenticated user accesses a protected endpoint
• AND refresh_attempt_count is already 2
• AND the AD API returns 401 on the 3rd refresh attempt
• THEN the system SHALL increment refresh_attempt_count to 3
• AND delete the session record from the database
• AND log the forced logout event with reason "Password may have been changed in AD"
• AND return status 401 with {"error": "Session terminated. Your password may have been changed. Please login again."}

Scenario: Session blocked due to previous 3 failed refresh attempts

• WHEN an authenticated user accesses a protected endpoint
• AND refresh_attempt_count is already 3 (from previous failed refreshes)
• THEN the system SHALL delete the session record immediately
• AND return status 401 with {"error": "Session expired due to authentication failures. Please login again."}

Requirement: 3-Day Inactivity Timeout

The system SHALL automatically invalidate user sessions that have been inactive for more than 3 days (72 hours). Inactivity is measured by the last_activity timestamp, which is updated on every API request.

Scenario: Reject request from inactive session

• WHEN a user accesses a protected endpoint with an internal_token
• AND the last_activity timestamp is more than 3 days (72 hours) in the past
• THEN the system SHALL delete the session record from the database
• AND return status 401 with {"error": "Session expired due to inactivity. Please login again."}

Scenario: Active user maintains session across multiple days

• WHEN a user logs in on Day 1
• AND makes at least one API request every 2 days (Day 2, Day 4, Day 6, etc.)
• THEN the system SHALL keep the session active indefinitely
• AND update last_activity on each request
• AND auto-refresh the AD token as needed

Requirement: Token-Based Authentication for Protected Routes

The system SHALL validate internal session tokens for protected API endpoints by checking the Authorization: Bearer <internal_token> header against the user_sessions table, enforcing inactivity timeout and auto-refreshing AD tokens when necessary.

Scenario: Access protected endpoint with valid active session

• WHEN a request includes header Authorization: Bearer <valid_internal_token>
• AND the session exists in user_sessions table
• AND last_activity is within 3 days
• THEN the system SHALL update last_activity to current time
• AND check and refresh AD token if needed (per auto-refresh requirement)
• AND allow the request to proceed with user identity available

Scenario: Access protected endpoint with invalid internal token

• WHEN a request includes an internal_token that does not exist in the user_sessions table
• THEN the system SHALL return status 401 with {"error": "Invalid or expired token"}

Scenario: Access protected endpoint without token

• WHEN a request to a protected endpoint omits the Authorization header
• THEN the system SHALL return status 401 with {"error": "Authentication required"}