Leo
6ee6fee8b9
credentials/ was a leftover duplicate — all credential routes already live in cypher-executor/src/routes/credentials.ts. Adds the SDD protocol, tech-stack, forbidden-list, component-architecture, and progress rules that guide Phase 1-6 refactors. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
71 lines
3.4 KiB
Markdown
71 lines
3.4 KiB
Markdown
# 技術棧硬限制
|
||
|
||
## 三層語言對應（絕對不可混用）
|
||
|
||
| 層級 | 語言 | 位置 | 職責 |
|
||
|-----|------|------|------|
|
||
| 零件（Component） | **TinyGo 或 AssemblyScript → WASM** | `registry/components/{name}/` | 所有業務邏輯 |
|
||
| 零件 Worker 包裝 | TypeScript（固定模板，不寫業務邏輯） | `.component-builds/{name}/` | WASI shim，stdin/stdout JSON |
|
||
| Orchestration Worker | TypeScript + Hono | `cypher-executor/` | HTTP routing、workflow 執行排程、host functions |
|
||
| CLI | TypeScript + Node.js | `cli/` | `acr` 指令 |
|
||
| Python SDK | Python | `python-sdk/` | HTTP thin wrapper + client 端加密 |
|
||
| JS SDK | TypeScript + Web Crypto | `js-sdk/` | HTTP thin wrapper + client 端加密 |
|
||
| Frontend | React 19 + Vite + Tailwind v4 | `landing/` | Cloudflare Pages |
|
||
|
||
## 零件實作規範
|
||
|
||
### 只有兩種合法語言
|
||
- **TinyGo**：`tinygo build -target=wasi -o {name}.wasm main.go`
|
||
- **AssemblyScript**：`asc main.ts --target release -o {name}.wasm`
|
||
|
||
### I/O 模型
|
||
- **stdin**：JSON input
|
||
- **stdout**：JSON output
|
||
- 不用 HTTP server，不監聽 socket（WASI preview1 沒 socket）
|
||
|
||
### Host Functions（零件呼叫外部能力的唯一管道）
|
||
在 `u6u` namespace 下：
|
||
|
||
| Host Function | 用途 |
|
||
|---|---|
|
||
| `u6u.http_request` | 發 HTTP 請求 |
|
||
| `u6u.kv_get` | 讀 Cloudflare KV（Worker 側依 key 前綴路由到正確 KV） |
|
||
| `u6u.crypto_decrypt` | AES-GCM 解密（encryption key 永不暴露給 WASM） |
|
||
| `u6u.crypto_sign_rs256` | RSA-SHA256 簽章（PKCS8 bytes 傳入） |
|
||
|
||
**所有 host function 在 `cypher-executor/src/lib/wasi-shim.ts` 實作**。零件透過 WASI import 使用。
|
||
|
||
## 資料儲存
|
||
|
||
| 儲存 | 用途 | Key 格式 |
|
||
|-----|------|---------|
|
||
| Cloudflare KV `WEBHOOKS` | workflow 定義（cypher binding YAML） | `webhook:{api_key}:{name}` |
|
||
| Cloudflare KV `CREDENTIALS_KV` | 加密 credential | `{api_key}:cred:{name}` |
|
||
| Cloudflare KV `RECIPES` | auth recipe / 動態 API recipe | `auth_recipe:{service}`, `rec_{hash}` |
|
||
| Cloudflare KV `USERS_KV` | 用戶資料 | `user:{api_key}` |
|
||
| Cloudflare KV `SESSIONS_KV` | session | `session:{token}` |
|
||
| Cloudflare KV `ANALYTICS_KV` | 執行分析 | `execution:{timestamp}:{id}` |
|
||
| Cloudflare KV `EXEC_CONTEXT` | workflow 執行中的 context | `ctx:{execution_id}:{node_id}` |
|
||
| Cloudflare R2 `WASM_BUCKET` | **只用於用戶自製零件**（Phase 5 以後啟用） | `{api_key}:cmp:{hash}` |
|
||
|
||
**警告：R2 不存平台內建零件的 WASM**。平台零件已 bundle 進各自的 Worker binary（`[[wasm_modules]]` 或 `import ... assert { type: 'webassembly' }`）。
|
||
|
||
## 加解密規範
|
||
|
||
- **演算法**：AES-GCM 256-bit
|
||
- **加密位置**：Client 端（CLI / Python SDK / JS SDK）
|
||
- Python：`cryptography` 套件
|
||
- JS：Web Crypto API（`crypto.subtle`）
|
||
- **解密位置**：Server 端 **WASM primitive**（透過 host function `crypto_decrypt`）
|
||
- cypher-executor TS **不解密**，只提供 host function
|
||
- `ENCRYPTION_KEY` 只在 Worker host function 內部讀取，**永不經 stdin / 回傳值傳給 WASM**
|
||
- **傳輸格式**：`{ name, encrypted, iv }`（iv base64、encrypted base64）
|
||
|
||
## 網路部署
|
||
|
||
- **平台 API**：`cypher.arcrun.dev`（cypher-executor）
|
||
- **每個零件**：獨立 Worker，URL 慣例 `{component-name-kebab}.arcrun.dev`
|
||
- 例：`auth-static-key.arcrun.dev`、`gmail.arcrun.dev`
|
||
- **Landing**：`arcrun.dev`
|
||
- **部署工具**：Wrangler
|