template-monorepo/docs/auth-unified-registration.md

# Gateway 統一註冊 — 設計規格

> **狀態**：已實作（PR 1–8 ✅；PR 9 文件修訂 ✅）  
> **修訂**：取代 [identity-member-design.md §3.4](./identity-member-design.md)「Gateway 不暴露 `/auth/register`」  
> **最後更新**：2026-05-21

## 1. 目標

使用者 **只與 Portal Gateway 互動** 完成註冊／首次登入；ZITADEL 作為 identity 後端（帳密、OIDC、鎖定），不作第二個註冊入口。

| 路徑 | 說明 |
|------|------|
| **A** | Email + Password + Email OTP 確認 |
| **B** | 上述流程 **必填 invite code**（Logic 驗證） |
| **C** | Social（Google 為 P0，可擴 Apple）— 同一註冊 UX，OAuth 前綁定 invite |

Logic 層負責商務驗證與跨 atomic usecase 編排；usecase 維持 atomic（見 [model.md §6.1](./model.md)）。

---

## 2. 為何比 ZITADEL Hosted 註冊好

- 單一 App / API，無「跳去 IdP 再回來」的割裂感
- 註冊表單可帶 **商務欄位**（條款版本、語系、marketing、invite、referral）
- 失敗補償與 audit 在 Gateway 可控
- 與現有 member OTP、notification 模板、`CreateUnverified` / `Activate` 直接對接

---

## 3. 三條註冊路徑（統一入口 UX）

```
                    ┌─────────────────────────────────────┐
                    │     前端：同一「註冊」頁 / Wizard      │
                    │  tenant + invite_code + 條款 (+ 語系)  │
                    └──────────────┬──────────────────────┘
                                   │
              ┌────────────────────┼────────────────────┐
              ▼                    ▼                    ▼
     Email + Password      Social (Google)        （未來 Apple）
              │                    │
              ▼                    ▼
   POST /auth/register    POST /auth/register/social/start
              │                    │ → oauth_url
              ▼                    ▼
   POST /auth/register/confirm   GET /auth/register/social/callback
              │                    │
              └────────┬───────────┘
                       ▼
              IssueTokenPair (CloudEP JWT)
```

### 3.1 路徑 A+B：Email 註冊

1. Logic 驗證：`tenant_slug`、`invite_code`、條款、密碼強度、email 格式
2. Logic 驗證並 **消耗** invite（見 §6）
3. `zitadel.CreateHumanUser`（email + password，org = tenant 對應 ZITADEL org）
4. `member.Lifecycle.CreateUnverified`（`origin=platform_native`，存 `zitadel_sub` 若 API 回傳）
5. Logic 寫入 **registration metadata**（§7）
6. `member.OTP.Generate`（`purpose=registration_email`）+ `notifier.Send`（`verify_registration_email`）
7. 回 `{ challenge_id, expires_in }`，**不發 JWT**
8. `POST /auth/register/confirm`：OTP verify → `Activate` → `IssueTokenPair`

### 3.2 路徑 C：Social 註冊（Google）

Invite **必填**；在 OAuth redirect **之前** 綁定 session，避免 callback 時無 invite。

1. `POST /auth/register/social/start`  
   Body：`tenant_slug`, `invite_code`, `provider=google`, `accept_terms_version`, 可選 `language`  
   Logic：驗 tenant + invite + 條款 → 建立 **registration session**（Redis）→ 回 `{ oauth_url, session_id }`
2. 使用者完成 Google OAuth → callback `GET /auth/register/social/callback?code=...&state=...`
3. Logic：換 token、驗 state、讀 session 取 invite → **消耗 invite**
4. `zitadel` 查/建 user（或 link）→ `member.Provisioning.EnsureFromOIDC`
5. 若 email 已在 ZITADEL verified → 直接 `Activate`；否則可走 OTP 或信任 IdP `email_verified`（**已決策：信任 Google email_verified=true 則 skip OTP**）
6. 寫 registration metadata → `IssueTokenPair`

> 已存在 member（同 tenant + zitadel_sub）→ 視為 **登入**，仍驗 invite 是否允許「新註冊 only」；若 invite 僅限新 user 且已存在 → `409` + 引導 login。

### 3.3 登入（非註冊）

| API | 說明 |
|-----|------|
| `POST /auth/login` | email + password → ZITADEL ROPG / token → member lookup → JWT |
| `POST /auth/token/exchange` | 保留：已登入 ZITADEL 的 id_token 換 JWT（企業 SSO、舊 client） |
| `POST /auth/login/social` | 可選：OAuth 僅登入、不經 register session（P1，與 register 分 state） |

---

## 4. API 規格（`generate/api/auth.api`）

### 4.1 公開 — 註冊

**POST `/api/v1/auth/register`**

Request:

```json
{
  "tenant_slug": "acme",
  "invite_code": "BETA-2026-XXXX",
  "email": "user@example.com",
  "password": "string",
  "display_name": "Daniel",
  "language": "zh-tw",
  "accept_terms_version": "2026-05-01",
  "marketing_opt_in": false
}
```

Response 200:

```json
{
  "code": 0,
  "data": {
    "challenge_id": "uuid",
    "expires_in": 300,
    "uid": "ACME-10000042"
  }
}
```

**POST `/api/v1/auth/register/confirm`**

```json
{
  "tenant_slug": "acme",
  "challenge_id": "uuid",
  "code": "482913"
}
```

Response 200: `{ access_token, refresh_token, expires_in, uid, token_type: "Bearer" }`

**POST `/api/v1/auth/register/resend`**

```json
{
  "tenant_slug": "acme",
  "challenge_id": "uuid"
}
```

**POST `/api/v1/auth/register/social/start`**

```json
{
  "tenant_slug": "acme",
  "invite_code": "BETA-2026-XXXX",
  "provider": "google",
  "accept_terms_version": "2026-05-01",
  "language": "zh-tw",
  "redirect_uri": "https://app.example.com/auth/callback"
}
```

Response: `{ oauth_url, session_id, expires_in }`

**GET `/api/v1/auth/register/social/callback`**

Query: `code`, `state`（含 session_id）  
Response: 302 到前端帶 token，或 JSON（依 `Accept` / 設定）

### 4.2 公開 — 登入 / Token

| Method | Path | 說明 |
|--------|------|------|
| POST | `/api/v1/auth/login` | email + password + tenant_slug |
| POST | `/api/v1/auth/token/refresh` | refresh_token |
| POST | `/api/v1/auth/token/exchange` | id_token + tenant_slug（SSO 備用） |
| POST | `/api/v1/auth/logout` | JWT，jti 黑名單 |

### 4.3 驗證 tag（`.api`）

- `register`: `required,email`, `password` min length, `invite_code` required
- 公開路由 **不走** JWT middleware；**走** rate limit（§12）

---

## 5. 分層與新增模組

```
internal/
  library/zitadel/           # HTTP client：CreateUser, VerifyPassword, OIDC token
  model/auth/
    config/
    domain/
      entity/registration_meta.go
      repository/invite.go, registration_session.go
      usecase/token.go, invite.go
    usecase/                 # atomic：IssueTokenPair, ValidateInvite, ConsumeInvite
  logic/auth/
    register_logic.go
    register_confirm_logic.go
    register_resend_logic.go
    register_social_start_logic.go
    register_social_callback_logic.go
    login_logic.go
  middleware/
    jwt_cloud_ep.go          # P1：取代 dev X-Tenant-ID header
```

**Logic 專屬商務（不下沉 usecase）**

- invite 是否必填、是否過期、是否限新 user
- 條款版本是否接受
- tenant 是否允許 B2C 註冊
- 密碼政策（client + server 雙重）
- 註冊 rate limit key 組合
- Social：OAuth state 與 registration session 綁定

**auth usecase（atomic）**

- `TokenUseCase.IssuePair / Refresh / Logout`
- `InviteUseCase.Validate / Consume`（或 tenant 模組，見 §6）

**禁止**：auth usecase 呼叫 member usecase；一律在 logic 編排。

---

## 6. Invite Code（B 必填）

### 6.1 資料模型（Mongo `invite_codes`）

| 欄位 | 說明 |
|------|------|
| tenant_id | 租戶 |
| code_hash | bcrypt/sha256，不明文存 |
| max_uses | 总次數 |
| used_count | 已用 |
| expires_at | 可選 |
| new_users_only | default true |
| created_at | |

索引：`(tenant_id, code_hash)` unique

### 6.2 流程

1. `ValidateInvite(tenant_id, plain_code)` → ok / `ErrInviteInvalid|Expired|Exhausted`
2. **Consume** 在 ZITADEL/member 建立 **之前** 用 Redis lock + Mongo `$inc used_count`（防并发超卖）
3. 若後續 ZITADEL 或 member 失敗 → **不回滚 invite**（已決策：防刷；可 admin 补发）。Logic 记录 audit + 人工处理阈值

可选 P1：`ReleaseInvite` 仅当失败发生在 Validate 后 30s 内且 ZITADEL 未创建。

---

## 7. Registration Metadata（Logic 要留的資料）

Collection：`registration_metadata` 或 member 子文档 `registration`：

| 欄位 | 來源 |
|------|------|
| tenant_id, uid | member |
| invite_code_id | 消耗后的 invite 记录 id |
| accept_terms_version | request |
| marketing_opt_in | request |
| registration_channel | `email` \| `google` |
| client_ip / user_agent | handler 注入 context |
| occurred_at | server |

写入时机：email 路径在 `CreateUnverified` 后；social 在 `EnsureFromOIDC` 后。

---

## 8. 狀態機

### Email 註冊

```
register → unverified (member) + zitadel user active
confirm OK → active + JWT
OTP max attempts → challenge locked
abort: cron 清理 7 天未 confirm 的 unverified + zitadel deactivate
```

### Social 註冊

```
social/start → registration_session (Redis TTL 10min, 含 invite_id)
callback OK → active + JWT
session 过期 → 重新 start
```

---

## 9. 失敗補償

| 步驟失敗 | 補償 |
|----------|------|
| invite 无效 | 直接 4xx，无 side effect |
| ZITADEL CreateUser 成功，member 失败 | Logic 调用 `zitadel.DeactivateUser(sub)` |
| member 成功，Send OTP 失败 | `OTP.Invalidate(challenge_id)` |
| confirm 时 Activate 失败 | 5xx，保留 challenge 可重试 confirm |

---

## 10. 錯誤碼（Logic / Usecase）

| 情境 | errb |
|------|------|
| invite 无效 | `InputInvalidFormat` 或 `ResNotFound("invite")` |
| invite 用尽 | `ResInsufficientQuota` |
| email 已注册 | `ResAlreadyExist` |
| OTP 错误 | `AuthForbidden` + cause |
| tenant 不允许注册 | `AuthForbidden` |
| 未 accept 条款 | `InputMissingRequired` |
| ZITADEL 下游失败 | `SvcThirdParty` |
| DB 失败 | `DBError` via wrapRepoErr |

---

## 11. 設定（`etc/gateway.yaml`）

```yaml
Auth:
  AccessExpire: 900
  RefreshExpire: 604800
  RegistrationSessionTTLSeconds: 600

Zitadel:
  Issuer: https://zitadel.internal
  MgmtURL: https://zitadel.internal/management/v1
  ServiceUserToken: ${ZITADEL_SERVICE_TOKEN}
  GoogleClientID: ...
  GoogleClientSecret: ...
  DefaultOrgID: ...   # 或 per-tenant 映射表

Member:
  Registration:
    RequireInviteCode: true
    UnverifiedRetentionDays: 7
    TrustSocialEmailVerified: true
```

---

## 12. Rate Limit（Redis）

| Key | 限制 |
|-----|------|
| `auth:register:ip:{ip}` | 10 / hour |
| `auth:register:email:{tenant}:{email}` | 3 / hour |
| `auth:register:invite_fail:{ip}` | 20 / hour |
| OTP resend | 沿用 member `VerifyRateStore` 或独立 cooldown |

---

## 13. 實施順序（PR 切分）

| PR | 内容 | 验收 |
|----|------|------|
| **1** | `library/zitadel` + config + 单元测试（mock server） | CreateUser / VerifyPassword |
| **2** | `model/auth` TokenUseCase（Issue/Refresh）+ JWT middleware 骨架 | 签/验 JWT |
| **3** | invite repository + InviteUseCase + mongo index | validate/consume |
| **4** | `auth.api` + Logic register + confirm + resend | curl 完整 email 注册 |
| **5** | registration_metadata + audit 字段 | Mongo 可查来源 |
| **6** | Social start/callback + registration session | Google 注册拿 JWT |
| **7** | `POST /auth/login` + 取代 dev header | member API Bearer 访问 |
| **8** | `/auth/token/exchange` + login/social 分离 | 企业 SSO 不冲突 |
| **9** | 文档修订 identity-member-design §3.4、§7.1 | 文档一致 ✅ |

---

## 14. 測試策略

- **单元**：invite consume 并发、OTP purpose、errb 映射
- **集成**：testcontainers Mongo/Redis + zitadel mock
- **E2E CLI**：`cmd/auth-register-test` 模拟 register → confirm → login
- **Social**：mock OAuth callback with fixed state

---

## 15. 與現有代码复用

| 已有 | 用途 |
|------|------|
| `Lifecycle.CreateUnverified` / `Activate` | email 注册 |
| `OTP.*` + `OTPPurposeRegistrationEmail` | 确认 |
| `Notifier` + `NotifyVerifyRegistrationEmail` | 寄信 |
| `Provisioning.EnsureFromOIDC` | social JIT |
| `Tenant.ResolveBySlug` | tenant_slug → tenant_id |
| `response.Write` + `errb` | HTTP 输出 |

---

## 16. 修訂 identity-member-design.md（已完成）

以下修訂已寫入 [identity-member-design.md](./identity-member-design.md)（v1.0.0，2026-05-21）：

- **§3.4**：Gateway 統一註冊 BFF（Email / Social / invite 必填）
- **§7.1**：auth.api 路由表（含實作狀態）
- **§8.1**：CloudEP JWT middleware + dev header fallback
- **§9.1**：login / token exchange 流程
- **§5.9 Case A**：標記為已實作
- **決策列 19**：註冊路徑決策更新

---

## 17. 前端契约（简要）

1. 注册页收集：`tenant_slug`, `invite_code`, 条款, 语言
2. Tab：Email | Google（同 invite + 条款）
3. Email：register → 输入 OTP → confirm → 存 token
4. Google：social/start → redirect → callback 页取 token
5. 错误：`409` 已存在 → 引导 login；invite 无效 → 留在注册页