下載檔加密

狀態：已收尾（母卡與十二張子卡 Done；STG／POC 未上、Agent image 未出包）｜日期：2026-10-29｜母卡 CM-3223、子卡 CM-3224～CM-3231、補卡 CM-3280～CM-3281｜前作 FR-166／166.1（Agent 主控台、分模組下載／匯出能力點、心跳下發模型、Agent 稽核 logging 管線）、FR-133（錯誤追蹤遮罩）、FR-145.3（結案報告草稿浮水印） 開發 branch：四個 repo（BE、FE、evidence-agent、jedi-python-package）2026-10-29 皆在 feature/FR-139；runner 開工 git branch --show-current 再確認，不對就停下問，不切

🔴 這份是設計決策，不是現況。 上線後的畫面與 API 現況看 SPEC 頁（各匯出頁的「下載檔案會加密」段、安全政策設定）；使用者怎麼開加密檔看使用手冊 docs/user-manual/encrypted-download-guide.md；套件用法看 jedi-file-protect README。

要擋的只有一件事：檔案下載到電腦後，別人走到這台電腦雙擊就能開。不擋檔案離開系統後的收回、到期、轉傳（決策者裁示先不做撤銷），不擋截圖與拍照。

端到端（一次下載）：使用者按匯出 → 前端問開關（快取）→ 開啟則對話框在瀏覽器端產 16 碼密碼、只顯示一次、複製後「下載」才亮 → 請求帶 X-File-Password header（不進 URL）→ 後端照常產檔 → 呼叫 jedi-file-protect 依副檔名加密（pdf／docx／xlsx 原生密碼；其他與多檔 AES zip）並蓋浮水印 → 寫 FILE_DOWNLOADED 稽核（不含密碼）→ 回檔帶 Cache-Control: no-store、X-Filename、X-File-Protected、X-File-Needs-7zip → 對話框關閉、密碼清掉。

Agent 主控台同一條，差別是開關值來自最後一次心跳、稽核事件先寫本機 system_logs 再隨心跳回主系統。

做完之後

• 任何「匯出／下載」按鈕都跳同一個對話框；下載到的 Word、Excel、PDF 雙擊要密碼；證據包、診斷包、圖片包是 AES .zip，要 7-Zip／WinZip／Keka 輸入密碼開。
• 安全政策多一個「檔案下載保護」開關，預設開；關掉時頁頂與系統總覽常駐警示、稽核事件一筆、之後每筆下載標「未加密」。
• 稽核事件頁看得到誰、何時、下載了哪份、有沒有加密。
• 一支新套件 jedi-file-protect，之後診斷包、資料庫備份下載、授權檔匯出都能直接用。

依賴：1 → 2（B1、F1 平行）→ 3（B2、F2、A1 平行）→ 4 → 5。決策者功課：發版前確認 jedi-iam（加一個政策鍵）與新套件 jedi-file-protect 兩支套件發版。

5.1 套件 jedi-file-protect（P1）

generate_password() -> str                     # 19 字元：4 段 × 4 碼英數，'-' 相連，去 0O1lI
protect(data: bytes, filename: str, password: str, *, watermark: WatermarkInfo | None = None) -> ProtectedFile
ProtectedFile(data: bytes, filename: str, needs_7zip: bool, encrypted: bool)

分派：.pdf → pypdf encrypt(user_password, algorithm="AES-256")（R6，禁 AES-256-R5／RC4）；.docx/.xlsx/.pptx → msoffcrypto agile；其他副檔名與多檔（傳 list[(name, bytes)]）→ py7zr SevenZipFile(password=…, header_encryption=True)，回 .7z。浮水印只對 pdf／docx 生效，內容「{nickname}（{login}） · {YYYY-MM-DD HH:mm} · Guidant AI」頁尾小字。零框架相依，照 jedi-masking 形狀；publish.sh 推 Nexus 等令。

5.2 主系統 helper（B1）

send_protected(buf, filename, mimetype, *, actor)：① 讀 request.headers["X-File-Password"]；② read_root_config_value("RUNTIME_CONFIG","FILE_DOWNLOAD_PROTECTION")，關閉→跳過加密；③ 開啟且無 header → BadRequestError(GRC_400xxx 缺少檔案密碼)；④ 呼叫套件；⑤ audit(FILE_DOWNLOADED, filename, format, encrypted, source)；⑥ send_file ＋ headers：Cache-Control: no-store、X-Filename（URL 編碼）、X-File-Protected: 0|1、X-File-Needs-7zip: 0|1，Access-Control-Expose-Headers 補這三個。密碼不得出現在任何 log 字串：helper 內不 log header，錯誤訊息不帶值；FR-133 遮罩規則補 X-File-Password header 名。

5.3 前端共用（F1）

useProtectedDownload().download(url, params, fallbackName)：讀 securityPolicyStore.fileDownloadProtection（登入後載一次，安全政策頁存檔後刷新）→ 開啟則開 ProtectedDownloadDialog（props：needs7zip 由呼叫端依格式預判，zip／多檔為 true）→ 使用者按複製（navigator.clipboard，失敗退回 execCommand）→ 下載鈕亮 → axios blob 帶 header → downloadBlob → 對話框關、密碼變數清空。密碼不進 Pinia、不進 localStorage。

5.4 Agent（A1、F3）

後端 core/console/file_protect.py 與主系統 helper 同介面、獨立實作（主系統那支綁 Flask-RESTful／EventCode／read_root_config_value）。心跳 observer file_protect_sync.py 照 ldap_source.py：收 data.file_protect.enabled 寫 data/file_protect.json；key 不存在（舊主系統）不動、檔案不存在視為 true。前端 console/ 直接 import 主站 ProtectedDownloadDialog 與 composable。

5.5 安全規則對照

批（Stage）＝工作坊同時開幾個小弟一起跑的那一組。底表在 handoff/cards.py，兩個斷言已過（依賴在更早的批；同批同 repo 不改同一檔）。

登記型檔只讓一張卡碰：BE event_code.py、remote_agent.py adapters、jedi-iam security_policy.py 都在 B1；FE 主站 i18n 由 F1 一次佔好 key（含 F2 用的）；api.js 不動（端點不變）。

套件異動（發版前統一確認）：新 jedi-file-protect、jedi-iam（加一鍵）；開發期 path dependency，不 commit path 改動。

1. DEV 稽核計畫頁按匯出 Word → 對話框 → 複製 → 下載 → 雙擊 Word 要密碼，貼上才開；按取消不產檔。
2. 匯出 ZIP → AES .zip，Windows 檔案總管與 macOS 內建解壓開不了、7-Zip／Keka 要密碼；檔名清單看得到、內容解不開。
3. DevTools：請求 header 有 X-File-Password、URL 無密碼、回應 Cache-Control: no-store；log/app.log grep 密碼字串為 0。
4. 稽核事件頁：FILE_DOWNLOADED 帶使用者、檔名、encrypted=true，payload 無密碼。
5. 安全政策關開關 → 頁頂與總覽出現「檔案下載保護已關閉」、稽核一筆 → 再匯出不跳對話框直接給明文、事件 encrypted=false → 開回來全恢復。
6. Agent：主控台檔案頁下載跳同一個對話框；拔網路重啟 Agent 仍加密；主系統關開關後下一跳不加密；從未連線的新 Agent 預設加密。
7. 開 PDF 每頁頁尾有下載者與時間。
8. 翻一遍所有有下載鈕的頁面，沒有一個直接給明文。
9. 預覽 PDF／docx／xlsx：畫面上沒有瀏覽器的下載／列印工具列，文件照常捲動縮放；主控台執行紀錄 HTML 報告預覽照舊、腳本不執行。

• PDF R5：pypdf algorithm 參數有 AES-256-R5，選錯比 RC4 還好破；P1 突變測試鎖 R6。
• Agent 沒收到開關值：必須視為開啟。反過來寫（預設關）會讓從未連線的新 Agent 整台不加密。
• 密碼進 log：任何一處 logger.info(request.headers) 都會漏；helper 不 log header，FR-133 遮罩補 header 名。
• navigator.clipboard 在 http＋IP 不存在（memory feedback_secure_context_only_browser_apis_break_on_http_ip）：複製鈕要退回 execCommand('copy')；crypto.getRandomValues 本身可用但 F1 要實測。
• e2e 與教育訓練會被打到：測試環境用管理員開關關掉，不另開測試後門。
• jedi-iam 發版：BOOL_KEYS 加鍵是套件改動，主系統 pin 要跟著升；發版前決策者確認。
• LibreOffice 轉出的 odt：沒有原生密碼，走 AES zip 包；B2 回寫註明。