Files

T

Leo d2618758e2 docs(sdd): SDD 生命週期鐵律遷移 + SDD 位置統一到 system-dev/docs/3-specs/

- 位置統一：舊 docs/3-specs/ 五份 SDD git mv 到 system-dev/docs/3-specs/，舊位置留 README 指針
- 狀態判定：0 份 active（無現行開發，合法）；paused×3（ingest-contract/kbdb-graph-extraction/plugin-install，等跨 repo 接通）；closed×2 入 archive/（arcrun-key-auth/blocks-edit-api 死件，附封存原因）
- 鋪檔（自 system-dev-template v1.15.0）：SDD-LIFECYCLE.md、pending-changes.md、sdd-guard.sh 新版、sdd-check.md、sdd-active-check.sh
- hook 掛載：settings.json PreToolUse Write|Edit 加 sdd-guard.sh
- CLAUDE.md：SDD 鐵律段（濃縮五條＋0-active 註明重啟先升 active）＋修正遷移後舊路徑
- 驗證：sdd-active-check exit 0；guard pipe-test 0-active 擋 code 寫入(exit 2)/md 放行(exit 0)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-07-17 17:04:12 +08:00

4.3 KiB

Raw Permalink Blame History

status, superseded_by

status	superseded_by
closed

封存（2026-07-17）：舊 KBDB 時代草稿（等 richblack review，帳號已 suspend）。key auth 屬基本盤 arcrun/kbdb 職責，非本插件範圍（2026-06-14 API-as-Wall 改寫後失效）。

KBDB — Arcrun Key Auth

建立：2026-05-05 狀態：草稿，待 richblack review

背景

KBDB 是 Arcrun 平台的子服務（對外統稱 Arcrun）。目前 KBDB 有兩種身份：

Internal：後端機器使用 KBDB_INTERNAL_TOKEN（hex secret）
Partner：外部系統使用 pk_live_xxx API Key，需先由 internal 建立 partner 記錄

問題：Arcrun 用戶（人類或 AI agent）登入 arcrun.dev 取得的 ak_xxx Key 無法直接存取 KBDB。要存 KBDB 目前沒有自助路徑。

目標

讓 Arcrun 用戶的 ak_xxx Key 直接可用於 KBDB，不需要額外申請第二把 Key。

設計決策

Key 格式不變

Arcrun Key 格式維持 ak_ 前綴（32 char hex），KBDB 新增對這個前綴的識別邏輯。不引入新的 Key 格式，不改 Arcrun 的 Key 產生邏輯。

KBDB 驗證路徑新增 `ak_` 支援

現有 index.ts auth middleware 的 Partner 驗證區塊（line 103）僅接受 pk_ 前綴。改為同時接受 pk_ 和 ak_，查詢同一張 partner 表（tpl-partner）。

if (effectiveToken.startsWith('pk_') || effectiveToken.startsWith('ak_')) {
  const partner = await lookupPartner(c.env.DB, tokenHash);
  ...
}

Arcrun 登入時寫入 KBDB partner 記錄

Arcrun cypher-executor/src/routes/auth.ts 的 OAuth callback（/auth/callback）在建立 UserRecord 後，呼叫 KBDB POST /partners 建立對應的 partner 記錄。

寫入時機：

新用戶首次登入 → 建立 partner 記錄（upsert 語意：若已存在則跳過）
Key rotate（PUT /me/api-key/rotate）→ 舊 partner revoke，建新 partner 記錄
Key revoke（DELETE /me/api-key）→ KBDB partner 設為 revoked

寫入內容：

{
  "name": "arcrun:{email}",
  "org_namespace": "arcrun:{email}",
  "api_key_hash": "SHA-256(ak_xxx)",
  "status": "active"
}

org_namespace 用 arcrun:{email} 格式，與 KBDB 原有的 partner namespace 不衝突。

Namespace 隔離

用戶只能存取自己 org_namespace 下的 KBDB 資料，與其他用戶完全隔離。 org_namespace = 'arcrun:{email}'，不是 admin，不會被提升為 internal。

服務啟用 UI（Dashboard /keys）

初期：Arcrun 用戶登入即自動建立 KBDB partner 記錄（無需勾選），因為「KBDB 是 Arcrun 的捆綁服務」，就像 n8n 登進去 Data Table 就在那裡。

未來（有計費需求時）：Dashboard /keys 頁面可加 toggle 控制，切換時呼叫 PATCH /me/kbdb → cypher-executor 再去 KBDB 啟用/停用 partner。

實作範圍（本 SDD）

KBDB 側（`matrix/kbdb/`）

修改 src/index.ts：

auth middleware Partner 驗證區塊：將 effectiveToken.startsWith('pk_') 改為同時接受 ak_

不改：

src/actions/partner-auth.ts（hashToken / lookupPartner 邏輯不變）
src/routes/partners.ts（POST /partners 介面不變，Arcrun 呼叫此 endpoint 建記錄）
D1 schema（tpl-partner template 不變）

Arcrun 側（`matrix/arcrun/cypher-executor/`）

屬於 frontend-redesign SDD 範圍內的後端補充，見該 SDD tasks.md。本 SDD 不負責 Arcrun 側實作，僅說明預期行為：

OAuth callback 成功後，以 KBDB_INTERNAL_TOKEN 呼叫 KBDB POST /partners
Key rotate 時：先 KBDB DELETE /admin/partners/{id} (revoke)，再建新記錄
Key revoke 時：KBDB DELETE /admin/partners/{id}

不做的事

不改 Key 格式（ak_ 保留）
不合併 Arcrun USERS_KV 和 KBDB partner 表（兩邊各自維護）
不做跨 namespace 的資料共享
不做 KBDB 側的 OAuth 驗證（KBDB 永遠只驗 token hash）

風險

風險	緩解
Arcrun 寫 KBDB 失敗（KBDB 暫時不可用）	登入仍成功；寫 KBDB 失敗靜默 log，用戶下次 rotate key 時重建
`ak_` Key 被猜測	32 char hex，entropy 足夠；與 `pk_` 同等安全
email 含特殊字元破壞 namespace	`org_namespace` 用 `arcrun:` + raw email，D1 存 TEXT 無問題

4.3 KiB Raw Permalink Blame History Unescape Escape