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>
This commit is contained in:
@@ -0,0 +1,124 @@
|
||||
---
|
||||
status: closed # active | draft | paused | closed（生命週期鐵律見 ../../SDD-LIFECYCLE.md）
|
||||
superseded_by: ""
|
||||
---
|
||||
|
||||
> **封存（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
|
||||
|
||||
寫入內容：
|
||||
```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 無問題 |
|
||||
@@ -0,0 +1,60 @@
|
||||
# KBDB Arcrun Key Auth — Tasks
|
||||
|
||||
> 建立：2026-05-05
|
||||
> 權威進度來源：本檔。完成一項立刻 `[x]`，不批次。
|
||||
|
||||
---
|
||||
|
||||
## Phase 0 — SDD 建立
|
||||
|
||||
- [x] 撰寫 `design.md`
|
||||
- [x] 撰寫 `tasks.md`（本檔）
|
||||
- [ ] richblack review + 認可 → 開 Phase 1
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 — KBDB auth middleware 接受 `ak_` Key
|
||||
|
||||
**修改檔案**：`matrix/kbdb/src/index.ts`
|
||||
|
||||
- [x] 1.1 將 line 103 的 `effectiveToken.startsWith('pk_')` 改為
|
||||
`effectiveToken.startsWith('pk_') || effectiveToken.startsWith('ak_')`
|
||||
- [ ] 1.2 本地跑現有測試確認不 break：`pnpm test`
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 — Arcrun OAuth callback 寫入 KBDB partner 記錄
|
||||
|
||||
**修改檔案**：`matrix/arcrun/cypher-executor/src/routes/auth.ts`
|
||||
|
||||
> 注意：此 Phase 需要 Arcrun 側有 `KBDB_INTERNAL_TOKEN` 和 `KBDB_BASE_URL` 兩個 env binding。
|
||||
|
||||
- [x] 2.1 在 `Bindings` type（`types.ts`）加入 `KBDB_INTERNAL_TOKEN?: string` 和 `KBDB_BASE_URL?: string`
|
||||
- [x] 2.2 建立 helper `src/lib/kbdb-partner.ts`：
|
||||
- `ensureKbdbPartner(env, email, apiKey)` → PUT /admin/partners/by-key-hash，失敗靜默 log
|
||||
- `revokeKbdbPartner(env, oldApiKey)` → DELETE /admin/partners/{id}，失敗靜默 log
|
||||
- [x] 2.3 在 OAuth callback（UserRecord 建立/取得後）呼叫 `ensureKbdbPartner`（fire-and-forget）
|
||||
- [x] 2.4 在 `PUT /me/api-key/rotate` 呼叫：`revokeKbdbPartner(oldKey)` + `ensureKbdbPartner(newKey)`
|
||||
- [x] 2.5 在 `DELETE /me/api-key` 呼叫 `revokeKbdbPartner`
|
||||
- [ ] 2.6 `wrangler secret put KBDB_INTERNAL_TOKEN`（cypher-executor Worker）← 需要人工執行
|
||||
- [x] 2.7 在 `wrangler.toml` 加 `KBDB_BASE_URL = "https://kbdb.finally.click"`
|
||||
|
||||
另外：KBDB `admin.ts` 新增 `PUT /admin/partners/by-key-hash` endpoint（upsert by hash，不產生新 key）。
|
||||
KBDB `types.ts` 加入 `KBDB_INTERNAL_TOKEN` 到 Bindings。
|
||||
KBDB `admin.ts` 放寬 `org_namespace` regex（允許 `arcrun:email@domain` 格式）。
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 — 驗證
|
||||
|
||||
- [ ] 3.1 新用戶 OAuth 登入 → 確認 KBDB partner 記錄建立（`GET /admin/partners` 查詢）
|
||||
- [ ] 3.2 用 `ak_xxx` Key 直接打 KBDB `GET /blocks` → 確認 200（非 401）
|
||||
- [ ] 3.3 Key rotate → 確認舊 Key 401，新 Key 200
|
||||
- [ ] 3.4 Key revoke → 確認舊 Key 401
|
||||
|
||||
---
|
||||
|
||||
## 目前狀態
|
||||
|
||||
- Phase 0 已完成（等 richblack 認可）
|
||||
- Phase 1–3 全部 `[ ]`，等認可後動工
|
||||
Reference in New Issue
Block a user