---
name: security-review
description: 在添加身份驗證、處理使用者輸入、管理秘密資訊 (Secrets)、建立 API 端點或實作支付/敏感功能時使用。提供全面的安全性檢查清單與模式。
---

# 安全性審查技能 (Security Review Skill)

本技能確保所有程式碼均遵循安全性最佳實踐，並識別潛在的漏洞與風險。

## 何時啟用

- 實作身份驗證 (Authentication) 或授權 (Authorization)。
- 處理使用者輸入內容或檔案上傳。
- 建立新的 API 端點。
- 處理秘密資訊 (Secrets) 或憑證 (Credentials)。
- 實作支付相關功能。
- 儲存或傳輸敏感數據。
- 整合第三方 API。

## 安全性檢查清單

### 1. 秘密資訊管理 (Secrets Management)

#### ❌ 嚴禁行為
```typescript
const apiKey = "sk-proj-xxxxx"  // 硬編碼的秘密資訊
const dbPassword = "password123" // 直接寫在原始碼中
```

#### ✅ 正確做法
```typescript
const apiKey = process.env.OPENAI_API_KEY
const dbUrl = process.env.DATABASE_URL

// 驗證秘密資訊是否存在
if (!apiKey) {
  throw new Error('未配置 OPENAI_API_KEY')
}
```

#### 驗證步驟
- [ ] 無任何硬編碼的 API 金鑰、權杖 (Tokens) 或密碼。
- [ ] 所有秘密資訊均儲存在環境變數中。
- [ ] `.env.local` 已加入 `.gitignore`。
- [ ] Git 提交歷史中無揭露秘密資訊。
- [ ] 生產環境的秘密資訊已在託管平台（如 Vercel, Railway）中配置。

### 2. 輸入驗證 (Input Validation)

#### 務必驗證所有使用者輸入
```typescript
import { z } from 'zod'

// 定義驗證架構 (Schema)
const CreateUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(1).max(100),
  age: z.number().int().min(0).max(150)
})

// 處理前先進行驗證
export async function createUser(input: unknown) {
  try {
    const validated = CreateUserSchema.parse(input)
    return await db.users.create(validated)
  } catch (error) {
    if (error instanceof z.ZodError) {
      return { success: false, errors: error.errors }
    }
    throw error
  }
}
```

#### 檔案上傳驗證
- 檢查大小（例如上限 5MB）。
- 檢查 MIME 類型（白名單機制）。
- 檢查副檔名（白名單機制）。

#### 驗證步驟
- [ ] 所有使用者輸入均透過 Schema 驗證。
- [ ] 限制檔案上傳（大小、類型、副檔名）。
- [ ] 查詢語句中不直接使用未經處理的使用者輸入。
- [ ] 使用白名單驗證（非黑名單）。
- [ ] 錯誤訊息不會洩漏敏感資訊。

### 3. 防止 SQL 注入 (SQL Injection Prevention)

#### ❌ 嚴禁拼接 SQL 字串
```typescript
// 危險 — 存在 SQL 注入漏洞
const query = `SELECT * FROM users WHERE email = '${userEmail}'`
```

#### ✅ 務必使用參數化查詢 (Parameterized Queries)
```typescript
// 安全 — 參數化查詢
const { data } = await supabase
  .from('users')
  .select('*')
  .eq('email', userEmail)
```

### 4. 身份驗證與授權

#### 權杖 (Token) 處理
- ❌ **錯誤**：儲存在 `localStorage`（易受 XSS 攻擊）。
- ✅ **正確**：使用 `httpOnly` Cookies。

#### 授權檢查
- 進行敏感操作前，務必重新驗證權限。
- 實作角色權限控制 (RBAC)。
- 在使用 Supabase 時，啟動資料列層級安全性 (RLS)。

### 5. 防止 XSS 攻擊

- **處理 HTML**：務必使用 `DOMPurify` 等工具進行清理。
- **內容安全政策 (CSP)**：配置適當的 CSP 標頭以限制來源。

### 6. 防止 CSRF 攻擊

- 在會變更狀態的操作中使用 CSRF Tokens。
- 將 Cookies 設定為 `SameSite=Strict` 或 `Lax`。

### 7. 速率限制 (Rate Limiting)

- 對所有 API 端點實例化速率限制。
- 對於高成本操作（如搜尋、AI 生成）設定更嚴格的限制。
- 實作基於 IP 或是基於使用者 ID 的限制。

### 8. 避免敏感資料外洩

- **紀錄 (Logging)**：嚴禁在紀錄中包含密碼、完整卡號或 Secrets。
- **錯誤訊息**：對使用者回傳通用報錯，僅在伺服器端紀錄詳細錯誤與堆疊 (Stack Trace)。

### 9. 依賴項安全性

- 定期執行 `npm audit`。
- 務必將 `package-lock.json` 或 `yarn.lock` 納入版本控制。
- 啟動 GitHub Dependabot 以獲取安全性更新提醒。

## 生產環境部署前安全性檢查清單 (Pre-Deployment)

- [ ] **秘密資訊**：確保無硬編碼內容，全數依賴環境變數。
- [ ] **輸入驗證**：所有入口點均已實作驗證。
- [ ] **SQL 注入**：所有資料庫操作均採參數化形式。
- [ ] **XSS/CSRF**：對內容進行清理並啟用防禦機制。
- [ ] **身份/授權**：權杖處理安全且角色檢查邏輯正確。
- [ ] **速率限制**：公共 API 端點已受保護。
- [ ] **HTTPS**：生產環境強制執行。
- [ ] **安全性標頭**：已配置 CSP, X-Frame-Options 等。
- [ ] **依賴項**：已掃描漏洞並更新至安全版本。
- [ ] **資料庫安全性**：RLS 與連線權限已正確設定。

---

**請記住**：安全性並非可選項。任何一個細微的漏洞都可能危害整個平台。如有疑慮，請採取最嚴格的安全策略。