# arcrun.dev Landing Page — SDD

> **目標**：給工程師一個門面，可以取得 API Key、管理 Key、探索 API（Swagger），同時藉此獲得會員 Email。
> **原則**：先快速可用，不追求功能完整。榮譽牆、Python Lib 是後期。

---

## 0. 範圍（這份 SDD 涵蓋）

| 功能 | 說明 |
|---|---|
| 首頁 Hero | 說明 arcrun 是什麼，CTA 取得 API Key |
| OAuth 登入 | Google / GitHub（用自己的 auth recipe — dogfooding） |
| API Key 管理 | 查看、Rotate、Revoke |
| Swagger UI | 嵌入 `/api`，讓工程師直接試打 |
| 榮譽牆 `/integrations` | 靜態骨架，先列 20 個 recipe，無動態數字 |
| 中英切換 | `?lang=zh` |

**不在本次範圍**：Python lib、Donate 整合、Social Proof 即時數字、貢獻者排行。

---

## 1. 技術選型

### 1.1 框架：Next.js（App Router）

**選 Next.js 而非 Astro 的原因**：
- `finally-click` 已有完整 Next.js + OAuth 回調實作，可直接複用模式
- API Key 管理頁有登入態保護需求，Next.js 的 middleware 最直接
- Cloudflare Pages 支援 Next.js（`@cloudflare/next-on-pages`）
- Astro 在動態路由保護上摩擦較多

### 1.2 部署：Cloudflare Pages

```
arcrun.dev → Cloudflare Pages（Next.js）
API calls → cypher.arcrun.dev（現有 Worker）
```

### 1.3 儲存：現有 cypher-executor CREDENTIALS_KV + 新增 USERS_KV

現有 cypher-executor Worker 已有：
- `CREDENTIALS_KV`：`{api_key}:cred:{name}` 存 tenant credentials
- `RECIPES`：auth recipes

新增需求：
- **USERS_KV**：存 user 帳號，key = `user:{provider}:{provider_user_id}`
  - value: `{ email, display_name, api_key, created_at, provider }`
- **SESSIONS_KV**：存 login session，key = `sess:{session_id}`
  - value: `{ api_key, email, expires_at }`
  - TTL = 7 天

兩個 KV 都加到 cypher-executor `wrangler.toml`。

### 1.4 OAuth — Dogfooding 自己的 Auth Recipe

登入用 arcrun 自己的 auth recipe：
- 不是用 arcrun auth recipe 的 `http_request` runner 去打第三方
- 而是 **直接複用 recipe YAML 裡定義的 OAuth App 設定（client_id/secret）**
- Worker 端實作 standard OAuth2 authorization_code flow

**支援提供商（MVP）**：
- Google（google_drive recipe 的 OAuth App，或另建 arcrun-login Google App）
- GitHub（github recipe 的 OAuth App）

登入 OAuth App 與 auth recipe 的 OAuth App **可以是同一個**（只要 scopes 包含 `openid profile email`），但更乾淨的做法是登入用獨立的 Google/GitHub App（只要 email scope），auth recipe 用的是資源存取 App。

**決策：登入用獨立 OAuth App**
- `GOOGLE_CLIENT_ID`、`GOOGLE_CLIENT_SECRET` — 只申請 `openid profile email`
- `GITHUB_CLIENT_ID`、`GITHUB_CLIENT_SECRET` — 只申請 `read:user` + `user:email`
- 以 Worker Secret 方式存入 cypher-executor

---

## 2. 頁面結構

```
arcrun.dev/
├── /                    首頁（Hero + Code snippet + CTA）
├── /login               登入頁（Google / GitHub 按鈕）
├── /auth/callback       OAuth callback（Pages Function）
├── /dashboard           API Key 管理（需登入）
├── /api                 Swagger UI（嵌入 swagger.json）
└── /integrations        服務目錄（靜態，20 個 recipe）
```

---

## 3. 登入 / OAuth 流程

### 3.1 流程圖

```
用戶點「Google 登入」
  → GET /auth/google/start（Worker 端）
    → redirect 到 Google OAuth（state = random, 存 SESSIONS_KV sess:state:{state} = {provider, redirect_back}）
  → 用戶同意
  → GET /auth/callback?code=...&state=...（Worker 端）
    → 驗 state
    → 用 code 換 access_token（POST google token endpoint）
    → 用 token 取 userinfo（GET google userinfo）
    → upsert USERS_KV user:{provider}:{provider_id} = {email, display_name, api_key, ...}
    → 若新用戶：呼叫現有 /register?email=... 取得 arcrun API Key
    → 建立 session：SESSIONS_KV sess:{session_id} = {api_key, email, ...}，TTL=7d
    → Set-Cookie: arcrun_session={session_id}; HttpOnly; Secure; SameSite=Lax
    → redirect 到 /dashboard
```

### 3.2 「若新用戶取得 API Key」的邏輯

現有 `/register` endpoint 接受 `email` 回傳 `api_key`（HMAC 確定性）。
但 landing page 需要的是**真正綁定到用戶帳號的 key**，且用戶可以 rotate/revoke。

**方案：延伸現有 register endpoint**

`/register` 目前：`HMAC(secret, email)` → 確定性 api_key，存 CREDENTIALS_KV

新增邏輯：
1. 若 USERS_KV 已有此 user → 直接用記錄裡的 api_key
2. 若新 user → 呼叫現有 `/register`（保持 HMAC 確定性邏輯）→ 拿到 api_key → 存入 USERS_KV

**好處**：不破壞現有 register 邏輯；登入後的 dashboard 顯示的 key = 現有 key = 封測用的 key。

### 3.3 Rotate / Revoke

- **Rotate**：產生新 UUID v4 key → 更新 USERS_KV 記錄 → 舊 key 失效（透過把新 key 加到 CREDENTIALS_KV，舊 key 的資料都跟著 API Key 命名空間走，所以 credentials 會留在舊 namespace）
  - 簡化版：Rotate 後顯示提示「您的 workflow credentials 已和舊 Key 分離，請重新設定」
- **Revoke**：USERS_KV 記錄 `revoked: true` → Worker middleware 拒絕此 key

---

## 4. API 端點（新增到 cypher-executor）

```
GET  /auth/google/start                   → redirect 到 Google OAuth
GET  /auth/github/start                   → redirect 到 GitHub OAuth
GET  /auth/callback?code=&state=          → 換 token、建立 session
POST /auth/logout                         → 清 session cookie
GET  /me                                  → 回傳當前登入用戶資訊（需 session cookie 或 API Key）
PUT  /me/api-key/rotate                   → 產生新 key
DELETE /me/api-key                        → Revoke（標記撤銷）
```

---

## 5. 前端頁面設計

### 5.1 首頁（/）

```
Hero:
  Stop fighting OAuth.
  One API key. Every service. Works anywhere.

  [Get API Key — Free]    [View on GitHub]

Before/After:
  40 行 OAuth 程式碼  →  auth.bind("google_drive")

Code Demo（三個 tab）：
  Python / JavaScript / HTTP（n8n 用戶）

[Get Free API Key] 按鈕
```

### 5.2 登入頁（/login）

```
arcrun

登入或建立帳號

[Continue with Google]
[Continue with GitHub]

不需要信用卡。API Key 立即可用。
```

### 5.3 Dashboard（/dashboard）

```
歡迎，{display_name}

您的 API Key
┌────────────────────────────────┐
│ ak_xxxxxxxxxxxxxxxxxxxx  [複製] │
└────────────────────────────────┘

[Rotate Key]  [Revoke Key]

使用說明：
  Authorization: Bearer {key}
  或 X-Arcrun-API-Key: {key}

[登出]
```

### 5.4 Swagger UI（/api）

- 嵌入 `<SwaggerUIBundle>` JS（CDN）
- `url: 'https://cypher.arcrun.dev/swagger.json'`（現有 Worker 已有 `/docs` openapi endpoint）
- 頂部說明：「這是 arcrun 的原始 API。Python / JS lib 是它的包裝，任何能發 HTTP request 的工具都能直接用。」

### 5.5 服務目錄（/integrations）

- 靜態列出 20 個 auth recipe（從 seed data 產生）
- 每個 recipe：名稱、認證方式（static_key / service_account）、所需 credentials
- 「找不到你要的服務？開 PR 貢獻 Recipe」CTA

---

## 6. 檔案結構

```
arcrun/landing/                         ← 新 Next.js 專案
├── app/
│   ├── layout.tsx
│   ├── page.tsx                        首頁
│   ├── login/
│   │   └── page.tsx
│   ├── dashboard/
│   │   ├── page.tsx
│   │   └── middleware.ts              （或 root middleware）
│   ├── api-docs/
│   │   └── page.tsx                   Swagger UI
│   └── integrations/
│       └── page.tsx
├── middleware.ts                       保護 /dashboard（讀 cookie）
├── lib/
│   └── auth.ts                        session helpers
├── public/
├── next.config.ts
├── package.json
└── wrangler.toml                      CF Pages 設定
```

cypher-executor 新增：
```
arcrun/cypher-executor/src/routes/
├── auth.ts                            ← 新增（OAuth start/callback/logout/me）
```

cypher-executor wrangler.toml 新增：
```toml
[[kv_namespaces]]
binding = "USERS_KV"
id = "<to be created>"

[[kv_namespaces]]
binding = "SESSIONS_KV"
id = "455d0505c7534883a4d4985ab8295857"
```

---

## 7. 環境變數 / Secrets

### cypher-executor（Worker Secrets）

```
GOOGLE_CLIENT_ID          Google OAuth App client_id（僅 openid profile email scope）
GOOGLE_CLIENT_SECRET      Google OAuth App client_secret
GITHUB_CLIENT_ID          GitHub OAuth App client_id（read:user + user:email scope）
GITHUB_CLIENT_SECRET      GitHub OAuth App client_secret
SESSION_SECRET            隨機 32 bytes，用於 HMAC session ID（或直接用 UUID）
```

### landing（Pages Environment Variables）

```
NEXT_PUBLIC_API_BASE      https://cypher.arcrun.dev
```

---

## 8. 實作步驟（Checklist）

### Phase 1：cypher-executor 後端擴充

- [x] `wrangler kv:namespace create USERS_KV` → 填入 wrangler.toml (id: 25bef01d079148919578894434d58c4d)
- [x] `wrangler kv:namespace create SESSIONS_KV` → 填入 wrangler.toml (id: 455d0505c7534883a4d4985ab8295857)
- [x] 建立 `arcrun/cypher-executor/src/routes/auth.ts`
  - [x] GET `/auth/google/start`
  - [x] GET `/auth/github/start`
  - [x] GET `/auth/callback`（換 token → userinfo → upsert USERS_KV → 建 session → Set-Cookie → redirect）
  - [x] POST `/auth/logout`
  - [x] GET `/me`（讀 session cookie 或 API Key header）
  - [x] PUT `/me/api-key/rotate`
  - [x] DELETE `/me/api-key`（revoke）
- [x] 在 `src/index.ts` 掛載 `authRouter`
- [ ] `wrangler secret put GOOGLE_CLIENT_ID` 等 4 個 secrets ← **用戶需自建 Google/GitHub OAuth App**
- [x] `wrangler deploy` ← 已部署（Worker version 7877857b）

### Phase 2：Next.js Landing 專案

- [x] `npx create-next-app@latest arcrun/landing --typescript --tailwind --app`
- [x] 設定 `@cloudflare/next-on-pages`（Next.js 15 + .npmrc legacy-peer-deps）
- [ ] 建立 `middleware.ts`（保護 /dashboard，讀 `arcrun_session` cookie）← 待做
- [x] 首頁（`app/page.tsx`）：Hero + Code Demo tab + CTA
- [x] 登入頁（`app/login/page.tsx`）：Google / GitHub 按鈕（href 到 cypher.arcrun.dev/auth/google/start）
- [x] Dashboard（`app/dashboard/page.tsx`）：顯示 API Key，Rotate / Revoke 按鈕
- [x] Swagger UI（`app/api-docs/page.tsx`）：client component，動態 import swagger-ui CDN
- [x] 服務目錄（`app/integrations/page.tsx`）：靜態，列 20 個 recipe
- [ ] 中英切換 ← 低優先，可延後
- [x] `wrangler pages deploy` → https://42a8d302.arcrun-landing.pages.dev
- [ ] Cloudflare dashboard 設定 arcrun.dev custom domain → arcrun-landing Pages project

### Phase 3：驗收（待 OAuth Secrets 填入後）

- [ ] Google / GitHub OAuth 完整流程（登入 → dashboard → 看到 key）
- [ ] Rotate：新 key 出現
- [ ] Revoke：舊 key 的 API 呼叫回傳 401
- [ ] Swagger UI 正常載入，可試打 `/health`
- [x] `/integrations` 正確列出 20 個服務

---

## 9. 待決事項（開始實作前確認）

| 問題 | 預設決策 |
|---|---|
| Google OAuth App 是否要另建（只有 email scope）? | 是，另建；auth recipe 的 App 不動 |
| Rotate 後舊 credentials 是否遷移？ | 不遷移，顯示提示 |
| Domain arcrun.dev 是否已購入且在 Cloudflare？ | 假設是（wrangler.toml 有設 zone_name） |
| 登入後 redirect 預設到 /dashboard | 是，可從 `?redirect=` 覆寫 |