---
tags: [credential, 部署, 架構決策, 踩坑]
gloss: 多個 Worker（auth primitive + cypher-executor）共享 ENCRYPTION_KEY，用 wrangler secret put 手動設進各 Worker secret store，不用 KV。
---
# 多 Worker ENCRYPTION_KEY 同步

← [[decisions/00-INDEX]]

**來源**：`system-dev/wiki/decisions-summary.md`（多 Worker ENCRYPTION_KEY 同步）、`.claude/rules/01-tech-stack.md` 加解密規範
**最後更新**：2026-06-27

## 摘要
Auth static_key / Auth service_account / cypher-executor 三個 Worker 都需 ENCRYPTION_KEY 來解密 credential。用各 Worker 的 secret store（非環境變數）存放；初期化時 `acr init` 生成一份 key，用 `wrangler secret put ENCRYPTION_KEY` 各設一次。

## 重點
- **Secret 存儲位置**：各 Worker 的 secret store（Cloudflare 原生機制），不是環境變數、不是 KV。環境變數會洩漏到日誌；KV 的 list 操作可能外洩。
- **初始化流程**：`acr init` 生成一份 32 字節隨機 key → 印出一次 → 用戶自己跑 `wrangler secret put ENCRYPTION_KEY --path <path>` 分別設進三個 Worker。
- **冪等性問題**：目前 `acr init` 多跑幾次會生成不同 key（不冪等）。長期應改成「init 檢查現有 config → 若存在 key 則重用舊的、否則生成新的」。
- **漂移陷阱**：若某個 Worker 的 key 遺漏或與其他 Worker 不同 → credential 解密失敗 → 表現為 401/403（用戶困惑，難debug）。
- **驗證方法**：init 完成後做一個 test workflow 打一個認證過的 API（如 gmail），確認三個 Worker 的 key 一致。

## 實體
- **ENCRYPTION_KEY**（加密密鑰）— 32 字節 AES-GCM 密鑰，用來解密用戶的 credential。
- **Secret store**（Cloudflare 密鑰存儲）— Worker 的原生機制，用 `wrangler secret put` 設置、runtime 讀取，內容不外洩。
- **密鑰漂移**（key drift）— 多個 Worker 持有不同版本的 ENCRYPTION_KEY，導致某些 Worker 解密失敗。
- **冪等性**（idempotency）— `acr init` 多次運行應產生同一結果（目前不達成）。
- **解密失敗**（decryption failure）— Worker 因 key 不匹配無法解密 credential，表現為 401/403 錯誤。

## 關聯
### 內文知識關係
- ENCRYPTION_KEY >> 分散存儲於 >> Secret store
- 密鑰漂移 >> 導致 >> 解密失敗
- 冪等性 >> 缺乏時 >> 重跑 init 造成 key 不一致
### 卡片關係
- （相關 memory：`encryption-key-drift-trap` — 解密失敗先比 key 指紋；屬 auto-memory 非 card）