template-monorepo/internal/model/member/README.md

# Member 模組 — OTP / TOTP

Member 模組目前提供兩組 **atomic usecase**（單一職責、互不呼叫）：

| UseCase | 用途 | 典型場景 |
|---------|------|----------|
| **OTP** | 伺服器產生的一次性數字碼 | 業務 email / 手機驗證、step-up 簡訊 |
| **TOTP** | RFC 6238 時間型驗證碼 | Google Authenticator 等 App 的 step-up MFA |

> **架構原則**：usecase **不可**呼叫其他 usecase。  
> 「產碼 → 寄信/簡訊 → 驗碼 → 更新 profile」這類多步驟流程，由 **logic 層**（或 CLI driver）編排。  
> 詳見 [`docs/model.md`](../../../docs/model.md) §6.1。

---

## 目錄結構

```
internal/model/member/
├── config/           # OTP / TOTP 設定
├── domain/           # 介面、enum、errors、redis key
│   ├── enum/
│   ├── repository/
│   └── usecase/
├── repository/       # Redis / memory 實作
├── totp/             # RFC 6238 純函式（模組專屬，非 internal/library）
├── usecase/          # OTPUseCase、TOTPUseCase 實作
└── README.md
```

---

## OTP（One-Time Password）

### 原理

1. **Generate**：伺服器用 `crypto/rand` 產生 N 位數字碼（預設 6 位），以 **bcrypt** 雜湊後存入 Redis，TTL 預設 300 秒。
2. **寄送**：明文驗證碼只在 `Generate` 回傳值中出現一次；logic 層負責呼叫 `notification.Notifier.Send` 投遞。
3. **Verify**：使用者提交 `challenge_id + code`，伺服器比對 bcrypt；成功後 **刪除 challenge**（一次性）。
4. **防暴力**：錯誤次數達 `MaxAttempts`（預設 5）即鎖定該 challenge。

```mermaid
sequenceDiagram
  participant Logic
  participant OTP as OTPUseCase
  participant Redis
  participant Notifier

  Logic->>OTP: Generate(tenant, uid, purpose, target)
  OTP->>Redis: Save challenge (bcrypt hash)
  OTP-->>Logic: challenge_id, plainCode
  Logic->>Notifier: Send(code, expires_in)
  Note over Logic: 使用者收到信/簡訊
  Logic->>OTP: Verify(challenge_id, code, uid, purpose)
  OTP->>Redis: Get + bcrypt compare
  OTP->>Redis: Delete challenge
  OTP-->>Logic: target (email/phone)
  Logic->>Logic: Profile.SetBusinessEmailVerified(...)
```

### Purpose（用途標籤）

```go
enum.OTPPurposeBusinessEmail  // 業務 email 驗證
enum.OTPPurposeBusinessPhone  // 業務 phone 驗證
enum.OTPPurposeStepUp         // step-up（未來 logic 層使用）
```

Verify 時 `Purpose` 必須與 Generate 一致，否則拒絕。

### API

```go
// 產碼
dto, plainCode, err := otpUC.Generate(ctx, &domusecase.GenerateOTPRequest{
    TenantID: "t1",
    UID:      "u1",
    Purpose:  enum.OTPPurposeBusinessEmail,
    Target:   "user@example.com",
})
// dto.ChallengeID → 給前端帶回 confirm API
// plainCode       → 只在此刻存在，交給 Notifier 寄出

// 驗碼
target, err := otpUC.Verify(ctx, &domusecase.VerifyOTPRequest{
    TenantID:    "t1",
    UID:         "u1",
    ChallengeID: dto.ChallengeID,
    Code:        "482913",
    Purpose:     enum.OTPPurposeBusinessEmail,
})
// 成功 → target == "user@example.com"，challenge 已刪除

// 寄送失敗時回滾
_ = otpUC.Invalidate(ctx, dto.ChallengeID)
```

### Rate limit（logic 層使用）

`VerifyRateStore` 提供 resend cooldown 與每日上限，**不在 OTPUseCase 內建**：

```go
// 冷卻（60 秒內不可重發）
ok, _ := verifyRate.TryResendLock(ctx, member.GetVerifyRateRedisKey(tenant, uid, "email"), 60*time.Second)

// 每日上限（預設 10 次）
count, _ := verifyRate.IncrDaily(ctx, member.GetVerifyDailyRedisKey(tenant, uid, "email"), 24*time.Hour)
```

---

## TOTP（Time-based OTP）

### 原理

遵循 **RFC 6238**，與 Google Authenticator / Authy 相容：

| 參數 | 預設值 |
|------|--------|
| 演算法 | HMAC-SHA1 |
| 週期 | 30 秒 |
| 位數 | 6 |
| 時間窗口 | ±1 step（容忍時鐘偏差） |

**儲存安全**：

- Secret 以 **AES-256-GCM** 加密（KEK = `Member.TOTP.SecretKEK`）後寫入 profile。
- 備援碼以 **bcrypt** 雜湊儲存，明文只在 `ConfirmEnroll` / `RegenerateBackupCodes` 回傳一次。
- 綁定前的 staged secret 暫存 Redis（`EnrollTTLSeconds`，預設 600 秒）。
- 驗碼成功後以 Redis 記錄 time step，**同一時間窗口內不可重放**。

```mermaid
sequenceDiagram
  participant User
  participant Logic
  participant TOTP as TOTPUseCase
  participant Redis
  participant Profile

  Note over Logic,Profile: 綁定階段
  Logic->>TOTP: StartEnroll(tenant, uid, account)
  TOTP->>Redis: Save encrypted staged secret
  TOTP-->>Logic: otpauth_url (QR code)
  User->>User: 掃碼加入 Authenticator
  Logic->>TOTP: ConfirmEnroll(tenant, uid, code)
  TOTP->>Profile: Save encrypted secret + backup hashes
  TOTP->>Redis: Delete staged secret
  TOTP-->>Logic: backup_codes[] (只顯示一次)

  Note over Logic,Profile: 日常使用（step-up）
  Logic->>TOTP: VerifyCode(tenant, uid, code)
  TOTP->>Profile: Decrypt secret
  TOTP->>Redis: MarkUsed(timestep) — 防重放
  TOTP-->>Logic: ok / err
```

### API

```go
// 1. 開始綁定 — 回傳 otpauth URL 供前端渲染 QR code
start, err := totpUC.StartEnroll(ctx, "t1", "u1", "user@example.com")
// start.OtpauthURL, start.Digits, start.PeriodSec, start.ExpiresIn

// 2. 確認綁定 — 使用者輸入 Authenticator 上的 6 碼
backupCodes, err := totpUC.ConfirmEnroll(ctx, "t1", "u1", "482913")
// backupCodes 只回傳這一次，請引導使用者妥善保存

// 3. step-up 驗碼 — TOTP 或備援碼皆可
err = totpUC.VerifyCode(ctx, "t1", "u1", "482913")   // 6 碼 TOTP
err = totpUC.VerifyCode(ctx, "t1", "u1", "ABCD-EFGH") // 備援碼（用過即刪）

// 4. 查狀態
status, err := totpUC.Status(ctx, "t1", "u1")
// status.Enrolled, status.BackupCodesRemaining

// 5. 停用 / 重產備援碼（logic 層應先要求 step-up）
_ = totpUC.Disable(ctx, "t1", "u1")
newCodes, err := totpUC.RegenerateBackupCodes(ctx, "t1", "u1")
```

### VerifyCode 判定順序

1. 長度 = 6 → 當 TOTP 驗（含 ±window）
2. 通過 → Redis 記錄 time step；已用過則回 `ErrTOTPCodeReplay`
3. TOTP 失敗 → 逐一 bcrypt 比對備援碼；命中則消耗一組
4. 皆失敗 → `ErrTOTPInvalidCode`

---

## 設定

`etc/gateway.dev.yaml` → `Member` 區塊：

```yaml
Member:
  OTP:
    Length: 6                  # 驗證碼位數
    TTLSeconds: 300            # challenge 存活時間
    MaxAttempts: 5             # 單 challenge 最大錯誤次數
    ResendCooldownSeconds: 60  # 重發冷卻（logic 層用 VerifyRateStore）
    DailyVerifyLimit: 10       # 每日上限（logic 層用 VerifyRateStore）
  TOTP:
    Issuer: CloudEP
    Algorithm: SHA1
    Digits: 6
    PeriodSeconds: 30
    Window: 1                  # ±1 time step
    BackupCodeCount: 10
    BackupCodeLength: 12
    EnrollTTLSeconds: 600      # 綁定 staged secret TTL
    ReplayTTLSeconds: 90       # 重放保護 TTL
    SecretKEK: ""              # 32-byte AES key（hex 64 字元或 base64）；留空則不啟用 TOTP
```

`SecretKEK` 可透過環境變數 `TOTP_SECRET_KEK` 注入（production 建議走 KMS / secret manager）。

---

## 裝配與注入

### Module factory

```go
mod, err := memberusecase.NewModuleFromParam(memberusecase.ModuleParam{
    Redis:  rds,
    Config: c.Member,
})
// mod.OTP        — 永遠有值（需 Redis）
// mod.TOTP       — SecretKEK 有設定時才有值，否則 nil
// mod.VerifyRate — resend / daily cap
// mod.Profile    — 預設 memory，P4 換 Mongo
```

### ServiceContext

Gateway 啟動時（Redis 就緒）自動注入：

```go
svc.MemberOTP         // domusecase.OTPUseCase
svc.MemberTOTP        // domusecase.TOTPUseCase（可能 nil）
svc.MemberVerifyRate  // VerifyRateStore
svc.MemberProfile     // ProfileRepository
```

---

## Logic 層編排範例

以下示範 **verify business email** 完整流程（logic 層職責，尚未有 HTTP handler）：

```go
// ── 發起驗證 ──
dto, code, err := svc.MemberOTP.Generate(ctx, &domusecase.GenerateOTPRequest{
    TenantID: tenant, UID: uid,
    Purpose: enum.OTPPurposeBusinessEmail,
    Target:  email,
})
if err != nil { return err }

_, err = svc.Notifier.Send(ctx, &notif.SendRequest{
    TenantID: tenant, UID: uid,
    Channel: enum.ChannelEmail, Kind: enum.NotifyVerifyEmail,
    Target: email, Locale: locale,
    Data: map[string]any{"code": code, "expires_in": dto.ExpiresIn},
    IdempotencyKey: dto.ChallengeID,
})
if err != nil {
    _ = svc.MemberOTP.Invalidate(ctx, dto.ChallengeID) // 寄送失敗回滾
    return err
}
return dto // 回傳 challenge_id 給前端

// ── 確認驗證 ──
target, err := svc.MemberOTP.Verify(ctx, &domusecase.VerifyOTPRequest{
    TenantID: tenant, UID: uid,
    ChallengeID: req.ChallengeID, Code: req.Code,
    Purpose: enum.OTPPurposeBusinessEmail,
})
if err != nil { return err }

return svc.MemberProfile.SetBusinessEmailVerified(ctx, tenant, uid, target)
```

`cmd/notify-test` 的 `startMemberVerify` 實作了發起驗證的前半段（Generate + Send），可作為 driver 參考：

```bash
make deps-up
make notify-test METHOD=member-email TO=you@example.com
make notify-test METHOD=member-phone PHONE=0912345678
```

---

## Redis Key 命名

| Key 前綴 | 用途 |
|----------|------|
| `member:otp:challenge:{id}` | OTP challenge 狀態 |
| `member:otp:challenge:{id}:attempts` | 錯誤次數計數 |
| `member:verify:rate:{tenant}:{uid}:{kind}` | 重發冷卻 |
| `member:verify:daily:{tenant}:{uid}:{kind}` | 每日上限 |
| `member:totp:enroll:{tenant}:{uid}` | 綁定 staged secret |
| `member:totp:used:{tenant}:{uid}:{timestep}` | TOTP 重放保護 |

Helper 函式見 `domain/redis.go`（`GetOTPChallengeRedisKey` 等）。

---

## 測試

### 單元測試

```bash
go test ./internal/model/member/... -v
make check
```

### 互動式 TOTP（Google Authenticator）

本機需 Redis，並在 `etc/gateway.dev.yaml` 設定 `Member.TOTP.SecretKEK`（example 已附 dev-only 占位 key）。

```bash
make deps-up
make totp-test
```

流程（單一 process，預設 `-step flow`）：

1. 終端機印出 **QR code** 與 **Secret key**
2. 手機 Google Authenticator → 掃描 QR（或手動輸入 Secret）
3. 輸入 Authenticator 上的 6 碼 → **ConfirmEnroll**（綁定完成，顯示備援碼）
4. 等 code 刷新後再輸入新 6 碼 → **VerifyCode**（step-up 驗證）
5. 自動測試重放保護（同一碼再驗應失敗）

進階：

```bash
make totp-test STEP=status
make totp-test STEP=disable
make totp-test STEP=verify CODE=482913
```

| 檔案 | 覆蓋 |
|------|------|
| `usecase/otp_usecase_test.go` | Generate/Verify、UID mismatch、max attempts lock |
| `usecase/totp_usecase_test.go` | 綁定、VerifyCode、備援碼、重放、Disable、Regenerate |
| `totp/totp_test.go` | RFC 6238 測試向量、window、otpauth URL |
| `library/crypto/aesgcm_test.go` | TOTP secret 加解密 |

---

## 尚未實作

- HTTP API / goctl handler（verify-email、verify-phone、totp enroll 等）
- Logic 層 confirm 流程（Verify + Profile flip + rate limit）
- `ProfileRepository` / `TOTPProfileRepository` 的 MongoDB 實作（目前 memory）
- Step-up token 簽發（auth 模組）

設計細節見 [`docs/identity-member-design.md`](../../../docs/identity-member-design.md) §5.2、§5.8。