# 安全性

## 概述

Neotask 採用以安全性為優先的架構設計。Gateway 預設綁定至 localhost，所有敏感資料在靜態時加密，代理程式執行可以在隔離容器中沙盒化。

## 網路安全

### 預設回送

Gateway 只監聽 `127.0.0.1`（localhost），除非您明確更改綁定模式。預設情況下無外部網路暴露。

### 驗證

所有 WebSocket 連接都需要驗證：

- **令牌驗證**, 不記名令牌（UUID 或自訂字串）
- **密碼驗證**, Bcrypt 雜湊密碼
- **受信任代理**, 來自反向代理的預驗證標頭
- **本機信任**, 回送連接隱式受信任

### 遠端存取安全

對於遠端存取，推薦的方法是 **Tailscale VPN** 或 **SSH 隧道**, , 永遠不要將 Gateway 直接暴露於網際網路。

## 裝置配對

### 配對如何運作

每個連接至 Gateway 的用戶端都必須配對：

1. 裝置呈現其身份（指紋 + 公鑰）
2. Gateway 發出配對挑戰（nonce）
3. 裝置用其私鑰簽署 nonce
4. 您透過 UI 核准裝置
5. Gateway 為未來的連接發出裝置令牌

### 信任模型

- **本機裝置**（回送）為了方便起見自動核准
- **非本機裝置**需要明確核准
- 裝置令牌儲存在本機，在重新連接時重複使用
- 裝置可以隨時撤銷

## 加密

### 靜態資料

- **AES-256-GCM**, 所有令牌、密鑰和 API 金鑰在靜態時加密
- **機器衍生金鑰**, 加密金鑰透過 scrypt 從裝置身份衍生
- **無明文儲存**, 令牌永遠不以明文儲存

### 傳輸中的資料

- **TLS**, 用於 API 通訊的 HTTPS
- **WSS**, 用於 Gateway 連接的 WebSocket Secure（使用 Tailscale Serve 或反向代理時）
- **HMAC 簽名**, 帶有 nonce 和時間戳記的請求完整性

## 沙盒

### 基於 Docker 的隔離

代理程式命令執行可以在 Docker 容器中沙盒化：

- **每代理程式設定檔**, 每個代理程式可以有自己的沙盒設定
- **資源限制**, 可設定的 CPU、記憶體和超時限制
- **網路隔離**, 容器可以與網路隔離
- **檔案系統限制**, 代理程式只能存取其工作空間
- **自訂映像**, 使用安裝了特定工具的預建映像

### 沙盒範圍

| 範圍 | 說明 |
|------|------|
| **每工作階段** | 每個工作階段使用全新容器 |
| **每代理程式** | 每個代理程式的持久容器 |
| **共享** | 跨代理程式的共享容器 |

### 工作空間存取

沙盒化代理程式可以存取其工作空間目錄（掛載至容器中），但無法存取工作空間外的主機檔案系統。

## 執行核准

控制代理程式可以在節點和 Gateway 主機上執行哪些命令：

### 模式

| 模式 | 說明 |
|------|------|
| **Allowlist** | 只有預先核准的命令才能執行 |
| **Ask** | 未知命令提示使用者核准 |
| **Full** | 無限制（謹慎使用） |

### 每節點設定

每個節點（macOS、無頭主機）都有自己的執行核准設定，儲存在本機。您可以允許特定二進位檔（例如 `/usr/bin/docker`、`/usr/local/bin/terraform`），同時封鎖其他所有內容。

## 提升模式

某些操作需要直接在 Gateway 主機上執行（而非在沙盒中）。提升模式：

- 受代理程式設定中明確權限的管控
- 只在 Gateway 主機上可用
- 預設停用
- 透過日誌記錄可審計

## 安全審計

內建安全審計檢查：

- 設定檔案權限（應為 600）
- 工作階段檔案權限
- Node.js 版本（安全修補）
- 明文密鑰偵測
- 外掛允許清單驗證
- 開放網路介面審計
- 驗證設定完整性

獲得許可後，審計可以自動修復許多問題。

## 最佳做法

1. **將 Gateway 保持在回送上**, 使用 Tailscale 或 SSH 進行遠端存取
2. **啟用沙盒**, 在 Docker 容器中執行代理程式命令
3. **使用執行允許清單**, 限制代理程式可以在節點上執行哪些命令
4. **設定驗證令牌**, 即使對於回送，也始終設定令牌驗證
5. **審查代理程式權限**, 盡可能使用最小工具設定檔
6. **保持 Neotask 更新**, 更新包含安全修補
7. **定期審計**, 執行安全審計以發現設定錯誤
8. **限制外掛載入**, 只安裝受信任的外掛