PROJECT-CONTORL/openspec/changes/archive/2026-01-05-add-file-encryption/tasks.md

Tasks: Add File Encryption

Backend Tasks

1. Create EncryptionKey model

• Create backend/app/models/encryption_key.py
• Update backend/app/models/__init__.py
• Add encryption_key_id FK to Attachment model
• Create Alembic migration
• 驗證: Migration 成功執行

2. Implement encryption service

• Create backend/app/services/encryption_service.py
• Add MASTER_KEY to config.py (from env var)
• Implement generate_key() - 產生新的 AES-256 金鑰
• Implement encrypt_key() - 使用 Master Key 加密金鑰
• Implement decrypt_key() - 使用 Master Key 解密金鑰
• Implement encrypt_file() - 串流式檔案加密 (AES-256-GCM)
• Implement decrypt_file() - 串流式檔案解密
• Add unit tests for encryption service
• 驗證: 加密解密測試通過

3. Create encryption key management API

• Create backend/app/api/admin/encryption_keys.py
• Implement GET /api/admin/encryption-keys - 列出金鑰（不含實際金鑰值）
• Implement POST /api/admin/encryption-keys - 建立新金鑰
• Implement POST /api/admin/encryption-keys/rotate - 金鑰輪換
• Add system admin only permission check
• Register router in main.py
• 驗證: API 可正常呼叫

4. Integrate encryption with attachment upload

• Modify backend/app/api/attachments/router.py upload endpoint
• Check project security_level before upload
• If confidential: encrypt file using encryption service
• Set is_encrypted = True and encryption_key_id
• Store encrypted file to NAS
• 驗證: 機密專案上傳的檔案為加密狀態

5. Integrate decryption with attachment download

• Modify backend/app/api/attachments/router.py download endpoint
• Check is_encrypted flag
• If encrypted: decrypt using encryption service before returning
• Maintain streaming for large files
• 驗證: 下載加密檔案可正確解密

6. Add encryption audit logging

• Log encryption operations (encrypt, decrypt, key_create, key_rotate)
• Include key_id, file_id, user_id, timestamp
• 驗證: 稽核日誌正確記錄加密操作

7. Add backend tests

• Test encryption service (encrypt/decrypt)
• Test key management API
• Test attachment upload with encryption
• Test attachment download with decryption
• Test key rotation
• 驗證: 所有測試通過

Configuration Tasks

8. Environment configuration

• Add MASTER_KEY to .env.example
• Document key generation procedure
• Document key backup recommendations
• 驗證: 文件完整

Task Dependencies

[1] EncryptionKey Model
      ↓
[2] Encryption Service
      ↓
[3] Key Management API ─────┐
      ↓                     │
[4] Upload Integration      │
      ↓                     │
[5] Download Integration    │
      ↓                     │
[6] Audit Logging          │
      ↓                     │
[7] Tests ←─────────────────┘
      ↓
[8] Configuration

• Tasks 1-7 為循序依賴
• Task 8 可平行進行