FR-039 Cloud ↔︎ Agent 認證設計 v2（自我註冊 + 憑證簽發 + 指紋 + 心跳）

狀態：已實作 + I2 端到端驗證通過（2026-06-19）。身分模型 v3（決策 B）已套用，見 §5(6)。 以 CLIENT_SERVER_REGISTRATION.txt 為準重整；v1（cloud 抓指紋 + ops 預發憑證 + UI 手動註冊）已被取代。

📦 部署一律使用 mTLS（AGENT_AUTH_MODE=full） —— none 僅供測試暫時停用認證。 完整部署操作手冊：evidence-agent/deploy/README.md。 資料面 mTLS 的踩雷（httpx 0.28 client 憑證要 SSLContext、下載走檔案自己的 agent、 base_url 必須 https）見 docs/changelog/2026-06-19-fr039-dataplane-mtls-download-i2-fixes.md。

            控制面（agent 主動撥出）                    資料面（cloud→agent，沿用）
agent ──register/heartbeat──▶ 雲端                雲端 ──/blob 上傳/下載/刪/預覽──▶ agent
   token + device_uuid          enroll:                (mTLS + JWT + 指紋 + status 檢查)
   + hardware + version         驗 token → upsert
                                → 簽發 agent 憑證回傳
                                → last_seen / online

• 控制面（註冊 + 心跳）：agent 主動撥出 → 永遠通（避防火牆）。
• 資料面（檔案）：維持 cloud→agent（已 ship）；跨外網用 tunnel（另案，本設計不含）。
• 認證：bootstrap 用 token + TLS；穩態用「雲端簽發的 agent 憑證」+ mTLS + JWT + 指紋。

device_uuid = sha256( product_uuid + "|" + machine_id + "|" + primary_mac )

• 三者正交（硬體 / OS 安裝 / 網卡）→ 移機、重灌、clone、換網卡 任一情況指紋就變。
• agent 主動收集後送（附件步驟一）；不再由雲端去抓（v1 做法）。
• Docker 階段：compose 掛 host 識別碼（/sys/.../product_uuid、/etc/machine-id 唯讀 + 部署腳本寫 MAC 檔）；原生封裝後直接讀，免掛載。
• 副作用：客戶重灌 OS / 搬機 → 指紋變 → 連線被擋 → 需「重新綁定」（人為明確動作）。

• 每 tenant 一組 registration token（installer 內建）；雲端存 hash。
• 用途：agent 第一次註冊時帶上 → 雲端據此判定歸屬哪個 tenant。
• 可在管理 UI 重新產生 / 撤銷（token 外洩時換一組，舊 installer 失效）。

① agent ──HTTPS(雲端 server cert) + token──▶ 雲端          ← bootstrap：只靠 token + TLS
② 雲端驗 token → tenant 確認 → agent 產 keypair 送 CSR
   → 雲端 CA 簽 agent server 憑證（SAN=agent host/IP）→ 回傳
③ 之後 agent 用此憑證跑 HTTPS server；資料面走 mTLS + JWT   ← 穩態

• 雲端側一次性：CA、雲端 client 憑證、JWT 簽章私鑰（RS256）放雲端 secret。
• 每台 agent：憑證自動簽發（不用 ops 手配）；agent 持 server cert+key + CA + JWT 公鑰。
• 輪替/撤銷：cert 有效期 + status=revoked（雲端拒呼叫）+ JWT 短效。

(1) 安裝 / 初始化（附件步驟一）

installer（現階段 Docker + .env）帶：雲端 endpoint + 該 tenant 的 registration token。agent 啟動算 device_uuid。

(2) 第一次心跳 = 註冊（附件步驟二）

agent ──HTTPS POST /api/1.0/agents/register──▶ 雲端
  payload: { token, device_uuid, base_url, hardware_info, agent_version, status:"registering" }

(3) 雲端 enroll + 綁定 + 簽憑證（附件步驟三）

驗 token → 對應 tenant
Upsert by (tenant_id, device_uuid)：有則更新、無則新增一列進 remote_agents
回傳：簽好的 agent 憑證（+ CA）；UI 上該設備自動出現（重新整理可見）

(4) 後續心跳（附件步驟五）

agent ──每 N 分鐘 POST /api/1.0/agents/heartbeat { device_uuid, status }──▶ 雲端
雲端更新 last_seen_at；超過門檻（如 30 分）未收到 → 視為 offline

即時 UI 延後：online/offline 由 last_seen_at 推算，管理頁重新整理時顯示。

(5) 資料面（沿用，cloud→agent）

雲端用 agent 回報的 base_url 打 /blob*：mTLS（雲端 client cert + 驗 agent cert）+ JWT（帶 bound device_uuid）+ agent 驗指紋 + status != revoked。

(6) 重新綁定 / 撤銷

⚠️ v3 修訂（2026-06-19，決策 B）：身分主鍵改為伺服器發的 agent_uid，rebind 已退場。 詳見 docs/analysis/2026-06-19-fr039-agent-identity-v3-uid-vs-fingerprint.md。

• 身分 = agent 持久化的 agent_uid（雲端首次發）；device_fingerprint 降為可更新屬性（attestation）。
• 換硬體 → register/heartbeat 依 agent_uid 自動更新指紋 + 記稽核（FILE_AGENT_FINGERPRINT_CHANGED），不冒新列、不需人工 rebind。
• 平台刪掉該 agent → 心跳回 404 → agent 自動重新 enroll（換新 uid）。對齊 osquery/Teleport/SPIRE 主流。
• rebind endpoint 留 dormant（FE 不放鈕）；下方原 v2 敘述保留供脈絡。

• 重灌/搬機 → device_uuid 變 → 連線/心跳對不上 → admin 確認後「重新綁定」（manager）。（v3 退場，改自動更新）
• 設備可疑 → 「撤銷」設 status=revoked → 雲端所有呼叫即拒（JWT 短效，幾乎即時）。（不變）

compliance.remote_agents 加欄（Phase 1 已加 device_fingerprint/status；本版再加）

base_url 改為 agent 註冊時回報（不再 UI 手打）；uid 仍是 registry 內部 id，upsert 鍵 = (tenant_id, device_fingerprint)。

新表 compliance.remote_agent_enroll_tokens（per-tenant 註冊 token）

agent 端 DB（fileagent.upload_files）不變。

• 指紋為 agent 軟體自報 → 擋一般憑證盜用（複製到別台跑原廠 agent，product_uuid/machine_id 不符）；擋不住完全控制機器 + 改 agent 原始碼偽造指紋。要更強需 TPM（未來）。

• 即時 UI（SocketIO 推播）：未來有需求再做，現階段重新整理。
• 封裝（.msi/.deb installer）：最後做，只影響「指紋讀取 / TLS 終結」末端細節，不影響模型。
• 資料面跨外網：網路層 tunnel，另案。