更新站規格

更新站只做四件事：

1. 認客戶：驗客戶出示的身分票或授權檔是 LC 簽的、綁的指紋就是來問的這台、不在拒絕名單。
2. 選版：在同主版號的已發布版（加上指定給這台先裝的草稿）裡，算出從現行版走到最新版的必經路徑。
3. 轉交：把決策者簽好的清單字串（signed_manifest）原樣放進回應，不解析、不改一個位元組。
4. 發網址：用 R2 S3 相容金鑰在 Worker 內算 15 分鐘預簽網址；金鑰本身從不離開 Worker。

清單驗章、版號遞增、主版號、sha256 全在客戶端做（見 發布簽章規格）。更新站被攻破時能做與不能做的事，見該頁「威脅對照」。

刻意不做的：沒有 KV、沒有 Durable Object、沒有排程（cron）、沒有對外發信。Worker 是無狀態的，唯一的模組層快取是 Access JWKS（10 分鐘，src/access.ts:14）。

客戶身分：身分票與授權檔

• 兩種格式都收：ticket（payload_type = update_ticket，LC 另簽的小 payload，只有 license_id、machine_fingerprint、product_major、kid，沒有客戶名稱）與 license（授權檔原文，含 issued_to）。兩者都帶時走 license（src/routes/client.ts:32）。BE 有票就只送票（update_site_client.py:99-104）。
• 信封格式：LC 的 v1 明文、v2 信封（payload = base64(zlib(canonical))）、v3 armor（-----BEGIN GUIDANT LICENSE----- 包 v2）三種都收（src/licenses.ts:7-9）。
• 公鑰表：PROD_KEYS 只有 LC 正式簽發站一把（src/licenses.ts:30-32）；DEV_KEYS 只有 LICENSE_KEYRING = "prod+dev" 才併入，這個值只寫在 wrangler.toml 的 [env.dev.vars]（:41-43）。漏設時預設只認 PROD。
• 借簽防護：同一把 LC 鑰也簽授權檔、身分票、完整性 manifest、解鎖碼，所以 payload_type 必須等於呼叫的那一種（缺鍵視為 license），不符回 wrong_payload_type（src/licenses.ts:184）。
• 主版號：product_major 缺欄視為 1；不是 ≥1 的整數就算格式錯（src/licenses.ts:161-167）。
• 刻意不看：expires_at（授權過期仍可升同主版號最新版）、時鐘回撥、時間窗（客戶端沒有私鑰簽不出新時間戳；重放風險與送原文相同，都綁指紋）。
• 成本上限：body 上限 MAX_LICENSE_TEXT + 4KB＝68KB（src/routes/client.ts:17）；payload 字串 64KB、解壓後 64KB，解壓邊讀邊累計，超過立刻丟（src/licenses.ts:23-24、:97-121）。

Access JWT 驗法

Access 只擋經過它的流量；Worker 自己再驗一次，只看「有沒有帶 header」等於誰都能偽造（src/access.ts:3-5）。

1. 設定三項 ACCESS_TEAM_DOMAIN、ACCESS_AUD、ACCESS_ALLOWED_EMAILS 缺一 → 所有 Access 身分 403（accessConfig，src/access.ts:69-80）。team domain 必須 https；只有 127.0.0.1／localhost 准用 http（本機假 JWKS）。
2. token 長度 ≤ 8KB、三段、header alg = RS256 且有 kid（:96-103）。
3. 先驗 claims 再抓鑰：aud 含 ACCESS_AUD、iss = team domain、exp／nbf 容許 60 秒誤差、email 必須存在（service token 沒有 email，一律不收）且在放行清單（:82-93）。
4. JWKS 從 <team>/cdn-cgi/access/certs 抓，快取 10 分鐘；未知 kid 觸發重抓，但兩次重抓至少隔 30 秒（:13-16、:52-62）。
5. RSASSA-PKCS1-v1_5 + SHA-256 驗簽章。

Bearer 優先：請求只要帶了 Authorization，就只當 CI token 看，不退回 Access（src/access.ts:146-157）。CLI 因此絕不能帶 Authorization，否則 publish 一律 403（cli/site.ts:4）。

後台的權限順序

handleAdmin（src/routes/admin.ts:330-346）的判定順序固定：

1. 認身分（identify），失敗 → 403 forbidden。沒身分的人連「這條路存不存在」都不該知道，所以身分在路由比對之前。
2. 比對路由：路徑不存在 → 404 not_found；路徑存在但方法不對 → 405。
3. CI 身分打 ci 不為 true 的路由 → 403 forbidden。
4. 跨站寫入擋（crossSiteWrite，:310-317）：非 GET／HEAD 時，帶 Origin 就必須同源（否則 403）；非 DELETE 時 content-type 必須是 application/json（否則 415 unsupported_media_type）。CLI 與 CI 不帶 Origin，不受影響。
5. 執行 handler。

• 成功：JSON，cache-control: no-store（src/http.ts:26-31）。/v1/report 成功回 204 無 body。
• 失敗：{"error": "<代碼>"}，部分後台錯誤多帶 reason、status、pending。只回代碼，不回原因——偽造者不該知道是 kid 錯還是簽章錯。
• 未預期例外：500 internal_error；log 只記路徑與錯誤種類，不記 body（客戶端 body 是整張授權檔，後台 body 可能是清單原文或 token 明文）（src/index.ts:12-27）。

三支都是 POST、body 為 JSON。共用的身分欄位（authenticate，src/routes/client.ts:25-39）：

身分判定順序（三端點相同）：欄位格式（400）→ 驗章與 payload_type（401）→ 照綁的指紋＝fingerprint（401）→ 拒絕名單（403）。拒絕名單排在主版號判定之前：被拒的授權連「有沒有新版」都不該知道。

POST /v1/check

releases[] 每一筆（ReleaseView，src/releases.ts:103-136）：

notes／impact／action 不在簽章內，發布後可在後台修字不必重簽。min_agent_version 不在 ReleaseView：客戶端從驗過章的清單 payload 讀。

POST /v1/download-url

客戶端對 ops 回應的檢查：回應沒明標 artifact: "ops" 一律不採用，因為不認得 artifact 的舊更新站會照回整包網址（update_site_client.py:121-139）。客戶端也只接受下載主機為 R2 帳號端點的網址（DOWNLOAD_HOSTS，update_site_client.py:28），更新站被冒用時不能把主機導去內網下載。

POST /v1/report

Agent 沒有自己的授權，身分仍是主機的票，agent_fingerprint 只用來分列。BE 的欄位對應：agent_rollout_service._unreported 送 agent_fingerprint、result（＝rollout 列的 status）、from_version、to_version（＝target_version）；送在交易外，送達才寫 reported_at（agent_rollout_service.py:415-443）。

instance_version_reports 寫入者只有兩支：/v1/check（只動版號與 last_seen）與 /v1/report（target=host）。發布前的「內部先裝全成功」只認 report 寫的結果，check 不算（internalTargetStatus，src/releases.ts:276-298）。

路由表在 src/routes/admin.ts:275-292。VERSION_SEG = [0-9A-Za-z.+-]{1,64}，進 handler 後再以版號格式驗一次（不符 400）。body 上限 MAX_SIGNED_MANIFEST + 8KB＝72KB（:44）。每次寫入都打一行稽核 log：{by, action, target, at}，by 是 Access 信箱或 ci:<token 名>，不記 body（:67-70）。

詳情物件

adminView＋internal_targets（src/routes/admin.ts:72-99）：

register-draft

body（parseDraftInput，src/releases.ts:196-214）：

主版號由 version 推，不收 CI 自報的 major。CI 實際送的是未簽的 release.json 整份（publish_draft.sh --data-binary @"$MANIFEST"），多出來的欄位（例如 ops_sha256）被忽略。

行為（registerDraft，src/releases.ts:226-250）：

• 版號不存在 → 新增一列 draft，r2_key 由 Worker 拼，retain_until = 現在 + 10 年。
• 版號已是 draft → 覆蓋 min_base_version、sha256、size、has_security_fix、created_at、min_agent_version；保留 internal_fingerprints、版本說明。若 sha256 變了（包換了），清掉那幾台內部先裝機器對這版的 last_upgrade_result，要重裝重報才算。
• 版號已 published 或 withdrawn → 409 {reason:"not_draft", status}。不然一支 CI token 就能把客戶正在裝的包換掉。

回 201：{version, major, status:"draft", upload:{bundle, manifest, sha256}}，upload 是三個 R2 目標 key，CI 照著傳、不自己拼（publish_draft.sh 先傳大包、再 .sha256、最後 release.json）。

publish

body：kid（^[0-9a-f]{16}$）、signed_manifest（string，非空，≤ 64KB，必須能 parse 成 JSON 物件；信封上若有 kid 必須等於 body 的 kid）（src/routes/admin.ts:148-173）。

驗法依序：

1. kid 在 signing_keys 是 revoked → 409 kid_revoked。印樣表沒登記這個 kid 不擋。
2. 版號不存在 → 404；withdrawn → 409 bad_status。
3. draft 第一次發布：internal_fingerprints 每一台都要 installed，否則 409 {reason:"internal_not_installed", pending:[…]}。清單為空時更新站放行（CLI 比這裡嚴，空清單直接拒絕）。
4. published 再送一次＝同版重簽：直接覆蓋 signed_manifest、kid、published_at，不再核內部先裝。

寫入：status = published、signed_manifest、kid、published_at（publishRelease，src/releases.ts:331-347）。更新站不驗清單簽章，它沒有、也不該有那把鑰；它只擋「一看就錯」的形狀。

其他寫入端點

客戶從現行版走到最新版，中間可能有「必經版」：某版的 min_base_version 高於客戶現行版時，客戶必須先升到一個 ≥ 該起始版的版本。planPath（src/releases.ts:82-101）：

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','secondaryColor':'#EEF2F3','secondaryTextColor':'#14201F','tertiaryColor':'#FBFCFC','tertiaryTextColor':'#14201F','lineColor':'#4A5A5C','textColor':'#14201F','mainBkg':'#E2F0F1','nodeBorder':'#0E7C86','nodeTextColor':'#14201F','edgeLabelBackground':'#FBFCFC','titleColor':'#14201F','clusterBkg':'#FBFCFC','clusterBorder':'#E4EAEB','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#EEF2F3','labelBoxBorderColor':'#C7D1D2','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF'}}}%%
flowchart TD
  A["候選＝看得到的版中，版號 ＞ 現行者<br/>（版號或 min_base 格式壞的丟掉）"] --> B{候選是空的？}
  B -- 是 --> N1["回 []（→ check 回 none）"]
  B -- 否 --> C["依 semver 排序，最高版＝latest<br/>at ＝ 現行版"]
  C --> D{at ＜ latest？}
  D -- 否 --> OK["回 path"]
  D -- 是 --> E["在『版號 ＞ at 且 at 的 X.Y.Z ≥ 該版 min_base』中<br/>挑最高的一版"]
  E --> F{挑得到？}
  F -- 否 --> N2["回 null（→ check 回 none，不回半條路）"]
  F -- 是 --> G["加進 path，at ＝ 那一版"] --> D

規則細節：

• 版號比較（src/versions.ts）：格式 X.Y.Z 或 X.Y.Z-後綴，與 BE release_json.sh 鎖同一格式。數字逐段比（不能字串比，"1.10.0" < "1.9.0"）；核心相同時有後綴的預覽版排在正式版之前。
• 必經判定只比 X.Y.Z（compareCore）：客戶在 1.27.0-beta.1 時，min_base_version = 1.27.0 的版也算可直升。
• 每一跳挑最高：跳數最少。走不到最新版（例如中間的必經版被撤回）就回 null，check 回 none——客戶端照半條路升完會停在一個沒人告訴它下一步的版本。
• 測試案例在 test/releases.spec.ts:65-92：無必經直升、單一必經 1.24.1 → 1.26.0 → 1.27.0、兩道必經、已最新回空、必經版缺回 null、預覽版看得到同核心正式版。

現況：D1 十個已發布版（1.27.1～1.27.10）的 min_base_version 都是 1.0.0，所以任何 1.x 客戶都是一跳直升 1.27.10。

key 只在 src/releases.ts 拼（:3-5）。主版號資料夾是授權邊界（D7），CI、客戶端、後台各拼一份遲早有人拼錯。

r2Key 的防呆（:16-22）：版號格式必須合法、major 必須是 ≥1 的整數且等於版號第一段、檔名 ^[A-Za-z0-9][A-Za-z0-9._-]*$ 且不含 ..，任一不符丟 ReleaseKeyError（後台轉成 400）。

R2 上的 release.json 是 CI 產的未簽版；簽好的信封只存在 D1 product_releases.signed_manifest，客戶從 check 回應拿。

預簽網址（presignDownload，:160-172）：用 aws4fetch 以 R2_ACCESS_KEY_ID／R2_SECRET_ACCESS_KEY 簽 S3 GET（region = auto、signQuery），X-Amz-Expires = 900（DOWNLOAD_URL_TTL_SECONDS = 15 * 60，:10）。網址本身只帶簽章、不帶金鑰。兩把金鑰任一沒設 → 503 download_unavailable。

保留：retain_until 在登記草稿時寫死為 10 年後（D29，RETAIN_YEARS = 10，:177、:216-220）。Worker 不刪任何 R2 物件；保留規則照這欄在 R2 設。

GET /admin 回 public/admin.html（452 行，打包進 Worker）。每次請求產一個 nonce，回應標頭（src/routes/admin.ts:258-273）：

• content-security-policy：default-src 'none'; script-src 'nonce-…'; style-src 'unsafe-inline'; connect-src 'self'; img-src 'self' data:; base-uri 'none'; form-action 'none'; frame-ancestors 'none'
• cache-control: no-store、x-content-type-options: nosniff、referrer-policy: no-referrer

頁面所有 API 呼叫用 credentials: "same-origin" 打 /admin/*，靠 Access cookie。四個分頁：

後台不能發布：publish 只收 Access 身分送回的簽好清單，而更新站沒有私鑰，簽不出任何東西。發布只能在決策者電腦跑 CLI。

「快過期，請重簽」標是發布清單 90 天效期的提醒。客戶端已不檢查清單有效期（見 發布簽章規格 的客戶端驗證段），這個標目前只是提示，不代表客戶會拒收。

只列名稱；值一律見 update-center .env、wrangler.toml、wrangler secret。

正式 Worker 現有 secret 五個：ACCESS_ALLOWED_EMAILS、ACCESS_AUD、ACCESS_TEAM_DOMAIN、R2_ACCESS_KEY_ID、R2_SECRET_ACCESS_KEY（wrangler secret list 實查）。

本機陷阱：沒有 .dev.vars 時 wrangler 會把 .env 整包（含 Cloudflare 權杖）當 Worker 變數載入。手測加 CLOUDFLARE_LOAD_DEV_VARS_FROM_DOT_ENV=false；vitest.config.ts 已在檔頭設好。

兩套 vitest，npm test 依序跑兩套：

（括號內為 it( 數。）

• 測試 D1 每次由 test/apply-migrations.ts 套 migrations/；R2 金鑰用假值 test-access-key-id。
• 真授權檔守衛：test/fixtures/*.license、*.ticket、*.json 是 LC 用 DEV 鑰真簽的檔（客戶欄位都是 DEV-FIXTURE），license-guard.spec.ts 用它們驗 WebCrypto 驗章與 LC 的 Python 實作逐位元組一致。紅了代表驗章實作和 LC 對不上，不要手改 fixture；重簽用 test/fixtures/sign_dev_fixtures.py（見 README）。
• CI 權限守衛：admin.spec.ts「CI token：只能打 register-draft」把路由表每一支都用 CI token 打一次（ADMIN_ROUTE_TABLE），新增路由忘了填 ci 會預設 403。
• schema 守衛：client.spec.ts「D1 schema 守衛」確認 instance_version_reports 沒有客戶名稱類欄位、六張主表都在。
• 工作坊工作區陷阱：repo 下有 .worktrees/<母卡號>/（工作坊小弟的工作區，已 gitignore），裡面也有一整套 test/。在 repo 根目錄手動跑 vitest 要排除它：npx vitest run --exclude '.worktrees/**'，否則會連工作區的測試一起跑、結果混在一起。
• 型別檢查 npm run typecheck（Worker、test、cli 三個 tsconfig）。

部署與對真庫套 migration 由首腦在測試期做，runner 不做（update-center CLAUDE.md）。

cd ~/Projects/Billows/Audit-Manager/update-center
npm ci
# 1. schema：照 migrations/ 順序套到正式 D1（已套過的會跳過，紀錄在 d1_migrations 表）
npx wrangler d1 migrations apply guidant-update-center --remote
# 2. Worker：predeploy 會先跑 typecheck 與兩套測試（含真授權檔守衛），紅了就不部署
npm run deploy          # = wrangler deploy
# 3. 第一次或換值時設 secret（互動輸入，不留在 shell history）
npx wrangler secret put R2_ACCESS_KEY_ID

• 順序：新欄位、新表先套 migration 再 deploy；Worker 新版讀不到欄位會 500。
• env.dev 不可部署成正式：[env.dev] 的 routes = [] 不可省，env 會繼承頂層 routes，--env dev 部署會把正式網域搶走（wrangler.toml 註解）。
• 唯讀查真庫：npx wrangler d1 execute guidant-update-center --remote --json --command "SELECT …"。
• LC 換鑰：LC 換正式簽發鑰或加站時要同步改 src/licenses.ts 的 PROD_KEYS 並重新部署，否則新照全回 401（:28-29）。

現況（2026-11-01 實查）：d1_migrations 已套 0001～0004；product_releases 10 列全部 published；instance_version_reports 3 列、agent_version_reports 2 列、release_download_log 15 列；signing_keys、ci_tokens、license_denylist 皆 0 列。也就是說，測試期的十個版本都是用測試章簽好後直接寫進 D1，沒有走 CI register-draft、CLI publish 與內部先裝（十列的 internal_fingerprints 都是 []）；正式出版流程（CI token、正式章、sync-keys）還沒啟用。

• 更新站資料表：七張 D1 表的欄位、索引、誰寫誰讀
• 發布簽章規格：信封格式、印章、CLI、客戶端驗證、威脅對照
• 更新中心 API 規格
• 升級指令規格：主機端 guidantai upgrade
• Agent 跟進規格：Agent 升級與代回報
• 時序圖
• 發版操作手冊
• 設計文件 §5.4、§5.8