管理金鑰與機密

使用本清單決定哪些值屬於執行階段環境、哪些產生到資料庫、哪些由外掛儲存。每一節說明輪換如何影響正在執行的站點。

在 Node.js 上，將執行階段機密放入託管平台的金鑰管理器，以便程序啟動時進入 process.env。對於 Worker，使用 wrangler secret put。不要把機密值放進 astro.config.mjs、wrangler.jsonc 或 import.meta.env；Vite 可能將建置時值嵌入伺服器綑綁。

概覽

加密金鑰

EMDASH_ENCRYPTION_KEY 加密以 type: "secret" 宣告的外掛設定。EmDash 使用 AES-GCM，並以外掛 ID 與設定鍵作為認證資料。格式錯誤的值會產生面向維運人員的啟動訊息，需要加密外掛設定的操作會 fail closed。無關的站點請求繼續運作。

以下命令產生格式正確的值。將其存入執行階段環境， 或在部署使用該變數時存為 Worker 機密。

npx emdash secrets generate
# emdash_enc_v1_<43 base64url chars>

# Cloudflare:
wrangler secret put EMDASH_ENCRYPTION_KEY

格式為 emdash_enc_v1_ 後接 32 個隨機位元組的無填充 base64url。該值由維運人員提供，不存入資料庫。將其保存在金鑰管理器以及單獨的復原備份中。

要輪換金鑰，將新值放在前面，並在逗號後保留舊值：

EMDASH_ENCRYPTION_KEY=emdash_enc_v1_<new-key>,emdash_enc_v1_<old-key>

EmDash 用第一把金鑰加密新的與重新儲存的值。讀取時使用儲存的 kid 指紋選擇較舊的金鑰。在移除舊金鑰之前重新儲存每個外掛機密，然後從僅含新金鑰的部署驗證這些整合。EmDash 目前不報告哪些金鑰 ID 仍在使用，因此請保留你重新儲存的憑證清單，並在每個整合通過該驗證之前不要移除舊金鑰。

產生的站點機密

兩個機密在首次使用時自動產生並持久化到 options 表，因此在請求、部署與 isolate 之間保持穩定。產生是原子的——並行冷啟動會收斂到一個值。

預覽機密

簽署預覽 URL（HMAC）。儲存為 emdash:preview_secret；32 個隨機位元組，base64url。

• 覆寫： 若需要跨多個程序使用同一機密，或出於稽核原因固定它，請設定 EMDASH_PREVIEW_SECRET（舊別名：PREVIEW_SECRET）。環境始終優先於儲存值。
• 輪換： 刪除 emdash:preview_secret 列（或變更環境變數）並重新部署。影響：先前簽發的預覽連結停止驗證。其他不會壞——下次預覽請求會產生（或從環境讀取）新機密。
• 若遺失： 沒有不可復原的內容。預覽連結設計上是短命的。

預覽 URL 如何建置與驗證見預覽指南。

IP 鹽

為用於留言速率限制的留言者 IP 位址 SHA-256 雜湊（留言上的 ip_hash）加鹽。儲存為 emdash:ip_salt。特定於站點，因此雜湊無法跨 EmDash 安裝關聯。

• 覆寫： 設定 EMDASH_IP_SALT。為向後相容，也會查閱 EMDASH_AUTH_SECRET / AUTH_SECRET——歷史上從它們衍生鹽的安裝會保持穩定雜湊。
• 輪換： 變更環境變數或刪除 emdash:ip_salt 列。影響：新留言提交會雜湊到不同值，因此所有人的速率限制計數重新開始。現有留言及其儲存的雜湊不受影響。
• 若遺失： 無資料遺失。僅速率限制連續性重設。

工作階段與 API 權杖

• 工作階段 使用 Astro 的工作階段儲存（Cloudflare 上為 Workers KV，Node 上為檔案系統）。Cookie 攜帶不透明工作階段 ID；沒有需要管理的簽署機密。登出結束工作階段，或清空工作階段儲存（例如 KV 命名空間）強制所有人重新登入。
• API 權杖（前綴 ec_pat_、ec_oat_、ec_ort_）是不透明的 256 位元隨機值；僅儲存其 SHA-256 雜湊。明文在建立時顯示一次。透過在管理後台撤銷並重新建立來輪換。
• 邀請、魔術連結與復原權杖 是單用途的，以 SHA-256 雜湊儲存在 auth_tokens 中，並有時限（邀請 7 天，魔術連結 15 分鐘）。

沒有需要主動備份或輪換的內容：資料庫洩漏只暴露雜湊，每個權杖都可從管理後台撤銷或重新簽發。

使用者提供的服務憑證

外部服務的憑證從環境讀取，從不寫入資料庫。在提供方輪換，更新變數，重新部署。

在 Cloudflare 上用 wrangler secret put 設定；本機開發放入 .env。Wrangler 讀取 .dev.vars 或 .env，不同時讀取，存在時 .dev.vars 優先。透過繫結的 R2 不需要存取金鑰變數，因為繫結授予執行階段存取。見媒體儲存。

外掛機密

外掛以 type: "secret" 宣告的設定（郵件提供方的 API 金鑰、表單 CAPTCHA 等）在管理 UI 中輸入，並加密到 options 表的 plugin:<id>:settings:<key> 下。即使相符的加密金鑰不可用，管理後台也只收到機密是否已設定，以便管理員取代無法讀取的憑證。外掛程式碼在其隔離執行階段透過 ctx.settings 讀取明文。儲存在已宣告設定結構描述之外的值，包括任意外掛 KV 與狀態項目，不使用此加密路徑。

• 憑證輪換： 在提供方輪換憑證，並將新值貼到外掛的設定頁。儲存會寫入新的加密信封。
• 明文移轉： 早期 EmDash 版本儲存的機密仍可讀。再次儲存每個值以加密它。
• 若加密金鑰遺失： 從單獨的金鑰備份還原相符的 EMDASH_ENCRYPTION_KEY。若無副本，請在每個受影響提供方取代憑證，並在設定新加密金鑰後輸入取代值。

CLI 憑證

emdash CLI 儲存兩類憑證，均位於 ~/.config/emdash/auth.json（遵循 XDG_CONFIG_HOME），以僅擁有者權限（0600）建立：

• 站點權杖 — emdash login 透過 OAuth 裝置流程對你的 EmDash 執行個體認證，並按執行個體 URL 儲存結果權杖。emdash logout 移除它；每次呼叫時，--token 或 EMDASH_TOKEN 覆寫儲存的權杖。
• Marketplace 權杖 — emdash plugin publish 透過 GitHub 裝置流程對 EmDash Marketplace 認證，並按 marketplace:<origin> 儲存結果 JWT。CI 發布請改設 EMDASH_MARKETPLACE_TOKEN——它優先於儲存的憑證。

遺失該檔案無害：再次執行 emdash login（或會重新執行裝置流程的 emdash plugin publish）。

外掛註冊表 CLI 憑證

單獨的 emdash-plugin CLI（套件 @emdash-cms/plugin-cli）面向實驗性的 AT Protocol 註冊表。在那裡發布與你的 AT Protocol 身分（發布者 DID）繫結——站點本身不持有發布憑證，安裝會對照歸因於該 DID 的發布記錄校驗和驗證產物。

• 透過 atproto OAuth 認證。OAuth 工作階段/狀態 blob 位於 ~/.emdash/oauth/，發布者身分（DID、handle、PDS）快取在 ~/.emdash/credentials.json；二者均以僅擁有者權限寫入。
• 在 CI 中透過 EMDASH_PUBLISHER_DID、EMDASH_PUBLISHER_HANDLE 與 EMDASH_PUBLISHER_PDS 提供身分；EMDASH_REGISTRY_URL 覆寫註冊表主機。來自 CI 的自動 publish 仍需要執行器上 ~/.emdash/oauth/ 中的 OAuth 工作階段檔案——僅環境變數不攜帶 OAuth 工作階段。
• 輪換或撤銷發布存取發生在你的 AT Protocol 帳戶（例如應用程式密碼），而非 EmDash 內。見 Atmosphere 認證。

輪換速查