PROJECT-CONTORL/openspec/specs/user-auth/spec.md

User Authentication & Authorization

Purpose

使用者認證與授權系統，透過外部認證 API 進行身份驗證，提供細部權限控制。

Requirements

Requirement: API-Based Authentication

系統 SHALL 限定使用外部認證 API (https://pj-auth-api.vercel.app) 進行登入認證，不支援其他認證方式。

Scenario: API 登入成功

• GIVEN 使用者擁有有效的企業帳號
• WHEN 使用者透過前端提交憑證
• THEN 系統呼叫 https://pj-auth-api.vercel.app 驗證憑證
• AND 驗證成功後建立 session 並回傳 JWT token

Scenario: API 登入失敗

• GIVEN 使用者提供無效的憑證
• WHEN 使用者嘗試登入
• THEN 認證 API 回傳錯誤
• AND 系統拒絕登入並顯示錯誤訊息
• AND 記錄失敗的登入嘗試

Scenario: 認證 API 無法連線

• GIVEN 認證 API 服務無法連線
• WHEN 使用者嘗試登入
• THEN 系統顯示服務暫時無法使用的訊息
• AND 記錄連線失敗事件

Requirement: System Administrator

系統 SHALL 預設一個系統管理員帳號，擁有所有權限。系統管理員帳號必須存在於外部認證系統，且登入流程仍需透過外部認證 API；不允許本地繞過認證。

Scenario: 預設管理員帳號

• GIVEN 系統初始化完成
• WHEN 系統啟動
• THEN 存在預設管理員帳號 ymirliu@panjit.com.tw
• AND 該帳號擁有 super_admin 角色
• AND 該帳號不可被刪除或降級

Scenario: 管理員登入流程

• GIVEN 管理員帳號 ymirliu@panjit.com.tw 需要登入
• WHEN 管理員提交憑證
• THEN 系統仍需呼叫 https://pj-auth-api.vercel.app 驗證
• AND 不存在任何本地繞過認證的機制
• AND 驗證成功後才授予 super_admin 權限

Scenario: 管理員全域權限

• GIVEN 管理員帳號 ymirliu@panjit.com.tw 已通過 API 認證並登入
• WHEN 管理員存取任何資源
• THEN 系統允許存取，無視部門隔離限制

Requirement: Role-Based Access Control

系統 SHALL 支援基於角色的存取控制 (RBAC)。

Scenario: 角色權限檢查

• GIVEN 使用者被指派特定角色 (如：工程師、主管、PMO)
• WHEN 使用者嘗試存取受保護的資源
• THEN 系統根據角色權限決定是否允許存取

Scenario: 角色指派

• GIVEN 管理員擁有使用者管理權限
• WHEN 管理員為使用者指派角色
• THEN 系統更新使用者的角色設定
• AND 新權限立即生效

Requirement: Department Isolation

系統 SHALL 實施部門級別的資料隔離，確保跨部門資料安全。

Scenario: 部門資料隔離

• GIVEN 使用者屬於研發部門
• WHEN 使用者嘗試存取廠務部門的專案
• THEN 系統拒絕存取並顯示無權限訊息

Scenario: 跨部門專案存取

• GIVEN 專案被設定為跨部門可見
• WHEN 不同部門的使用者嘗試存取該專案
• THEN 系統根據專案的 Security_Level 設定決定是否允許存取

Requirement: Session Management

系統 SHALL 管理使用者 session，包含過期與登出機制。

Scenario: Session 過期

• GIVEN 使用者已登入系統
• WHEN Session 超過設定的有效期限
• THEN 系統自動使 session 失效
• AND 使用者需重新登入

Scenario: 主動登出

• GIVEN 使用者已登入系統
• WHEN 使用者執行登出操作
• THEN 系統銷毀 session 並清除 token

Requirement: Access Token Expiry

Access tokens SHALL expire within 60 minutes to limit exposure window in case of token compromise.

Scenario: Access token expiry

• WHEN an access token issued 61 minutes ago is used for API authentication
• THEN request is rejected with 401 Unauthorized
• AND error indicates "Token expired"

Requirement: Refresh Token Support

The system SHALL support refresh tokens for seamless session continuity without requiring re-authentication.

Scenario: Refresh valid token

• WHEN POST to /api/auth/refresh with valid refresh token
• THEN new access token is issued
• AND new refresh token is issued via rotation
• AND old refresh token is invalidated

Scenario: Refresh expired token

• WHEN POST to /api/auth/refresh with expired refresh token
• THEN request is rejected with 401 Unauthorized
• AND user must re-authenticate via login

Scenario: Automatic frontend refresh

• WHEN access token expires in less than 5 minutes
• AND frontend prepares to make API call
• THEN token is automatically refreshed first
• AND original request proceeds with new token

Requirement: API Rate Limiting

The system SHALL implement rate limiting to protect against brute force attacks and DoS attempts.

Scenario: Login rate limit enforcement

• GIVEN a client IP has made 5 login attempts within 1 minute
• WHEN the client attempts another login
• THEN the system returns HTTP 429 Too Many Requests
• AND the response includes a Retry-After header

Scenario: Rate limit window reset

• GIVEN a client has exceeded the rate limit
• WHEN the rate limit window expires (1 minute)
• THEN the client can make new requests

Scenario: Rate limit per IP

• GIVEN rate limiting is IP-based
• WHEN different IPs make requests
• THEN each IP has its own rate limit counter

Requirement: Comprehensive API Rate Limiting

The system SHALL enforce rate limits on all sensitive API endpoints to prevent abuse and ensure service availability.

Scenario: Task creation rate limit exceeded

• WHEN user exceeds 60 task creation requests per minute
• THEN system returns 429 Too Many Requests
• THEN response includes Retry-After header

Scenario: Report generation rate limit exceeded

• WHEN user exceeds 5 report generation requests per minute
• THEN system returns 429 Too Many Requests
• THEN response includes rate limit headers

Scenario: Rate limit headers provided

• WHEN user makes any rate-limited API request
• THEN response includes X-RateLimit-Limit header
• THEN response includes X-RateLimit-Remaining header
• THEN response includes X-RateLimit-Reset header

Scenario: Rate limit window reset

• WHEN rate limit window expires
• THEN user can make requests again up to the limit
• THEN X-RateLimit-Remaining resets to maximum

Requirement: Input Length Validation

The system SHALL enforce maximum length limits on all user-provided string inputs to prevent DoS attacks and database overflow.

Scenario: Task title exceeds maximum length

• WHEN user submits a task with title longer than 500 characters
• THEN system returns 422 Validation Error with descriptive message

Scenario: Description field within limits

• WHEN user submits content with description under 10000 characters
• THEN system accepts the input and processes normally

Requirement: CORS Security

The system SHALL explicitly define allowed CORS methods and headers instead of using wildcards to reduce attack surface.

Scenario: Request with standard headers

• WHEN a cross-origin request includes Content-Type, Authorization, or X-CSRF-Token headers
• THEN the request is allowed

Scenario: Request with non-standard header

• WHEN a cross-origin request includes a non-whitelisted custom header
• THEN CORS preflight fails and request is rejected

Requirement: Secure WebSocket Authentication

The system SHALL authenticate WebSocket connections without exposing tokens in URL query parameters. In production environments, query parameter authentication SHALL be disabled.

Scenario: WebSocket connection with token in first message

• WHEN client connects to WebSocket endpoint without a query token
• THEN server waits for authentication message containing JWT token
• THEN server validates token before accepting further messages
• THEN server sends an authentication acknowledgment message

Scenario: WebSocket connection with invalid token

• WHEN client sends an invalid or expired token
• THEN server sends an error message indicating invalid or expired token
• THEN server closes the connection with an authentication error code

Scenario: WebSocket connection timeout without authentication

• WHEN client connects but does not send authentication within 10 seconds
• THEN server closes the connection with appropriate error code

Scenario: Query parameter auth in production

• WHEN production environment and WebSocket connection includes token in query parameter
• THEN connection is rejected with code 4002
• AND error message indicates "Query parameter auth disabled in production"

Requirement: WebSocket Connection Limits

The system SHALL limit each user to a maximum of 5 concurrent WebSocket connections to prevent resource exhaustion.

Scenario: User exceeds connection limit

• WHEN user already has 5 active WebSocket connections
• AND user attempts to open a 6th connection
• THEN connection is rejected with code 4005
• AND error message indicates "Too many connections"

Scenario: User within connection limit

• WHEN user has fewer than 5 active connections
• AND user opens a new WebSocket connection
• THEN connection is accepted

Requirement: Path Traversal Protection

The system SHALL prevent file path traversal attacks by validating all file paths resolve within the designated storage directory.

Scenario: Path traversal attempt detected

• WHEN request contains file path with "../" or absolute path outside storage
• THEN system rejects request and logs security warning
• THEN system returns 403 Forbidden error

Scenario: Valid file path within storage

• WHEN request contains valid relative file path
• THEN system resolves path and verifies it is within storage directory
• THEN system processes file operation normally

Requirement: JWT Secret Validation

The system SHALL validate JWT secret key strength on startup.

Scenario: Weak secret rejected

• WHEN the configured JWT secret is less than 32 characters
• THEN the system SHALL log a critical warning
• AND optionally refuse to start in production mode

Scenario: Low entropy secret warning

• WHEN the JWT secret has low entropy (repeating patterns, common words)
• THEN the system SHALL log a security warning

Requirement: CSRF Protection

The system SHALL protect all state-changing operations (POST, PUT, PATCH, DELETE) with CSRF tokens.

Scenario: POST request without CSRF token

• WHEN an authenticated user makes a POST request without X-CSRF-Token header
• THEN the request SHALL be rejected with 403 Forbidden
• AND error message indicates "CSRF token is required"

Scenario: PUT/PATCH/DELETE request without CSRF token

• WHEN an authenticated user makes a PUT, PATCH, or DELETE request without X-CSRF-Token header
• THEN the request SHALL be rejected with 403 Forbidden

Scenario: Valid CSRF token accepted

• WHEN a state-changing request includes a valid CSRF token
• THEN the request SHALL proceed normally

Scenario: Public endpoints exempt from CSRF

• WHEN POST to /api/auth/login or other public endpoints
• THEN CSRF token is not required

Data Model

pjctrl_users
├── id: UUID (PK)
├── email: VARCHAR(200) UNIQUE
├── name: VARCHAR(200)
├── department_id: UUID (FK)
├── role_id: UUID (FK)
├── skills: JSON
├── capacity: DECIMAL (週工時上限)
├── is_active: BOOLEAN
├── is_system_admin: BOOLEAN DEFAULT false (不可修改的系統管理員標記)
├── created_at: TIMESTAMP
└── updated_at: TIMESTAMP

pjctrl_departments
├── id: UUID (PK)
├── name: VARCHAR(100)
├── parent_id: UUID (FK, self-reference)
└── created_at: TIMESTAMP

pjctrl_roles
├── id: UUID (PK)
├── name: VARCHAR(50)
├── permissions: JSON
├── is_system_role: BOOLEAN DEFAULT false
└── created_at: TIMESTAMP

Default Data (Seed)

-- 預設系統管理員角色
INSERT INTO pjctrl_roles (id, name, permissions, is_system_role) VALUES
('00000000-0000-0000-0000-000000000001', 'super_admin', '{"all": true}', true);

-- 預設系統管理員帳號
INSERT INTO pjctrl_users (id, email, name, role_id, is_active, is_system_admin) VALUES
('00000000-0000-0000-0000-000000000001', 'ymirliu@panjit.com.tw', 'System Administrator',
 '00000000-0000-0000-0000-000000000001', true, true);

External Dependencies

• Authentication API: https://pj-auth-api.vercel.app (唯一認證方式)

Authentication Flow

┌─────────┐     ┌─────────────┐     ┌──────────────────────────┐
│  User   │────▶│  Frontend   │────▶│  pj-auth-api.vercel.app  │
└─────────┘     └─────────────┘     └──────────────────────────┘
                      │                         │
                      │◀────── JWT Token ───────│
                      │
                      ▼
               ┌─────────────┐
               │   Backend   │ (驗證 JWT, 建立 Session)
               └─────────────┘