feat: KBDB-graph 插件獨立 — 全面改寫成走基本盤 API（API-as-Wall）

按 leo 鐵律（2026-06-14）把插件從「直接 SQL 操作基本盤表」改寫成
「只透過基本盤 arcrun/kbdb HTTP API 讀寫」。零建表、零 migration、零 SQL。

- 新增 src/lib/kbdb-client.ts：唯一對外通道，封裝 entries/templates/records API
- 新增 src/lib/templates.ts：triplet/entity template 定義（替代建表）
- 改寫 21 個違規 action（triplet/graph/entity/search）→ 走 client，圖在插件層記憶體組裝
- 移除所有 migrations、D1/Vectorize/AI 綁定；embedding/語意搜尋歸基本盤 optional 模組
- index.ts 只掛 triplets/graph/entities/search 路由；基本盤路由歸 arcrun/kbdb
- 測試改走 mock client（純 node）；裁剪 CLAUDE.md 只留 graph 插件 + 鐵律
- 修正 SDD design.md「讀現狀推翻鐵律」的錯誤判斷（共用 D1 → API-as-Wall）

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/3-specs/arcrun-key-auth/design.md

@@ -0,0 +1,117 @@
+# 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
+
+寫入內容：
+```json
+{
+  "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 側實作，僅說明預期行為：
+
+1. OAuth callback 成功後，以 `KBDB_INTERNAL_TOKEN` 呼叫 KBDB `POST /partners`
+2. Key rotate 時：先 KBDB `DELETE /admin/partners/{id}` (revoke)，再建新記錄
+3. 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 無問題 |