# Server9300 Web Auth API

Base URL: `https://my.keylockr.app`

這份文件是 `/web/*` 外部 JSON 契約的權威來源。SSO、AppData、KPS 與綁定生命週期的
權威契約另見 [`api.5.sso.md`](../server9305_v3apikl/api.5.sso.md)。WWW 發布副本位於
`https://keylockr.app/assets/developers/web-auth-api.md`。

## 1. Transport 與 closed-schema 規則

- API 呼叫使用 `POST`、`Content-Type: application/json`、`Accept: application/json`。
- JSON root 必須是 object。Request schema 是 closed：只能傳各 endpoint 列出的欄位；禁止 duplicate
  key、unknown field、錯誤型別及 trailing JSON value。Server 的相容性容忍不是外部契約，caller
  不得依賴。
- 可正常處理的成功與業務錯誤都使用 HTTP `200`。先檢查 `_res`，再按 endpoint 與 discriminator
  解碼其餘欄位。HTTP `404`／`405`、無法解析的 body 或非 JSON response 是 transport failure，
  不得當成業務 response。
- 每個 success variant 都是 closed schema。收到 unknown／duplicate field、缺少 required field、
  錯誤型別或未列出的 discriminator 組合時，consumer 必須 fail closed。
- Request 中的 `string` 均為 UTF-8 JSON string；標記 required 時不得省略。Server 會在文件明示處
  trim／canonicalize，但 consumer 應先傳送乾淨值。

所有 JSON success 都含 `_res: "ok"`。符合 request schema 後進入業務驗證的 JSON error 只有以下形狀：

```ts
type WebError = {
  _res: "err",
  code: string,
  msg?: string,
  color?: "danger" | "warning" | "info",
  reportable?: boolean,
  ref_id?: string,
}
```

Error object 的 optional metadata 只供顯示／回報；不得改變 `code` 的控制流程。Alias 格式錯誤可回
`Wrong Email`、`Email not allowed +`、`No number`、`Invalid US phone number`、
`Invalid Australia phone number`、`Invalid Taiwan phone number`、`Invalid Japan phone number` 或
`alias_forbid_24hours`。頻率限制使用 KPS 通用格式 `try_later N seconds/milliseconds` 或
`try_later_auto N seconds/milliseconds`。缺少 required 欄位、錯誤型別、unknown／duplicate field、
trailing value、無效 JSON 與相依服務故障不提供穩定 business-error shape；它們一律是 protocol／transport
failure。Consumer 應 fail closed，不得從目前 provider 的容忍、panic 或 framework response 猜測契約。

## 2. Web SSO context 與 trust metadata

以下三個 optional request 欄位只適用於 `alias_verify` 與 `reg_choose_num`：

| 欄位 | 型別 | 規則 |
|---|---|---|
| `app_tag` | string | 已註冊服務的 effective App Tag；trim 後區分大小寫。未設定自訂 tag 時傳十進位 Service ID。 |
| `sign_pk` | string | 本次登入的 32-byte Ed25519 public credential，standard Base64。 |
| `enc_pk` | string | Client-owned 的持久 32-byte X25519 identity key，standard Base64；backend-owned 忽略 request 值並使用服務登記公鑰。 |

`svc_id` 不是外部欄位。只有 canonical `app_tag` 非空時 response 才進入 Web SSO context；此時
`safe_ready` 必定出現在既有使用者／完成註冊的 success response。有效 SSO 整合必須傳
`app_tag + sign_pk`；client ownership 另須傳 `enc_pk`，backend ownership 則以 MyDeveloper
登記的 `encrypt_pk_base64` 為唯一 effective `enc_pk`。服務無法解析或權威 key 非 canonical
32 bytes 時 fail closed：主登入仍可成功，但不回 `app_id`。

Trust metadata 的權威來源：

| 欄位 | 權威語意 |
|---|---|
| `safe_id` | KeyLockr `users.id`；第三方穩定 user ID。 |
| `nickname` | KeyLockr 使用者目前顯示名稱；不是穩定 identity。 |
| `token` | 9300 新建並持久化的 session token；只與同一 `safe_id` 配對使用。絕對有效期 30 天，閒置約 7 天即失效（見第 7 節）；登出會立即撤銷。 |
| `safe_ready` | `users.encrypt_pk` 是否存在的提示；不是授權、能力或 binding 證明。 |
| `app_id` | 9300 已解析服務及驗證 public keys 後回傳的 KeyLockr binding ID；只有 field 存在時才可使用。 |

`app_id` **可能是既有 binding，也可能是本次 alias 流程新建的 binding**：

- 非 AppData 服務按 `(safe_id, app_tag, effective_enc_pk)` 復用既有 SSO binding，並在 OTP
  成功的同一 transaction 內把 `sign_pk` 更新為目前 credential；沒有時可建立純 SSO binding。
  同一 `sign_pk` 不得 claim 不同 `enc_pk`，alias 路徑也不得輪換 AP `enc_pk`。selector 會在同一
  namespace lock 內跨 SSO／AP 檢查 effective `enc_pk`；enc identity 已被另一 binding type 占用與
  sign credential alias 都 fail closed、response 不帶 optional `app_id`，但內部診斷分類彼此獨立。
- credential 更新、server-side generation 遞增與共用持久 invalidation outbox 在同一 PostgreSQL
  transaction 提交。9305 在 outbox 排空前不會信任殘留 identity/result cache；這不新增 Web Auth
  request／response 欄位，也不把 optional supplement 失敗提升為 OTP 主登入失敗。
- AppData 服務只復用 Safe 先前授權的同一 encryption identity，且 `(safe_id, app_tag)` 必須精確對應唯一有效
  AppData file；alias 驗證永不建立 AppData binding 或授予 filekey。
- Response 沒有「本次新建」的、綁定 transaction 的 ownership proof。Consumer 因此不得在 callback、
  finish、session persistence 或後續 AppData 失敗時自動呼叫 `app_logout` 或 `app_del`。普通登出只在
  仍持有目前 credential 時明確呼叫 `app_logout`；`app_del` 只可在完整驗證成功後，由使用者明確選擇
  永久斷開該 binding，最後一個 AppData reference 才會同時刪除共用 file。

## 3. `POST /web/alias_ping`

檢查使用者狀態，可選擇傳送驗證碼。此 endpoint 不回傳 nickname。

```ts
type AliasPingRequest = {
  id: string,       // email、mobile 或 Safe ID
  send_code?: bool, // 省略等同 false
}
```

Success 是下列 closed union：

```ts
type AliasPingSuccess =
  | { _res: "ok", status: "safe_id", safe_id: string }
  | { _res: "ok", status: "user_404" }
  | { _res: "ok", status: "existed", code_sent?: true }
  | { _res: "ok", status: "user_404", code_sent: true }
```

規則：

- `status="safe_id"` 只表示該 Safe ID 存在，且必須有 `safe_id`；不傳驗證碼。
- Safe ID 不存在時是沒有 `safe_id`／`code_sent` 的 `status="user_404"`。
- Email/mobile 已存在時是 `status="existed"`，**不**回傳 `safe_id`（驗證碼通過前不得把 alias 換成 Safe ID）；
  不存在時是 `user_404`。Consumer 須從 `alias_verify` 成功回應取得 `safe_id`。
- Email/mobile 且 request `send_code=true` 時必須有 literal `code_sent=true`；省略或 false 時該欄位
  必須不存在。`code_sent=false` 不是合法 response。
- 有效碼不覆寫、不重寄、不延長原 600 秒期限；`code_sent=true` 亦可表示先前碼仍可使用。
  尚在交付時提供 `try_later 1 seconds`。一般身分的規範 alias／目的地各限 3 次／600 秒、10 次／86400 秒，
  Gmail／Googlemail 統一為 gmail.com，去點及 `+tag` 合併目的地；其他供應者不推定子位址等價。兩服務共用預算，全域預設 100 次／60 秒，
  正整數 `otp.send_per_minute` 可調整。其中「尚未註冊的目的地」另受子額度限制，最多佔全域每分鐘預算的 50%，
所以大量灌入不存在的帳號不會耗盡已註冊使用者的發碼額度（已註冊目的地之間互相耗盡仍屬殘餘風險）；耗盡提供 `try_later N seconds`，N 為耗盡桶剩餘 PTTL 的最大值向上取整為秒，至少一秒。
  拒絕不重設計數或期限；耗盡計數缺少期限時拒絕，不虛構等待值。
  Redis 錯誤／未知回執拒絕，不盲重送交付；特殊操作共用政策，期限仍為 300 秒。
  已分配的保留測試身分沿固定碼分支，不作實際投遞或發碼費用計數，其他原子與驗證保護共用。

## 4. `POST /web/alias_verify`

驗證 email/mobile 的六位驗證碼。成功會消費驗證碼。

```ts
type AliasVerifyRequest = {
  id: string,
  code: string,
  app_tag?: string,
  sign_pk?: string,
  enc_pk?: string,
}
```

既有使用者成功會新建 session token；`/web/*` 一律只以 `safe_id + token` 辨識，不簽發、不讀取、不清除任何 Cookie
（遷移說明見第 7 節）。簽發在單一資料庫交易內完成，只有提交成功後才回傳 token；提交結果無法確認時回
`session_issue_failed`，不回傳 token，使用者重新驗證即可：

```ts
type AliasVerifyExisting =
  | {
      _res: "ok", status: "existed",
      safe_id: string, nickname: string, token: string,
    }
  | {
      _res: "ok", status: "existed",
      safe_id: string, nickname: string, token: string,
      safe_ready: boolean, app_id?: string,
    }
```

第二個 variant 只在 Web SSO context 使用；`safe_ready` 必填，`app_id` 只有第 2 節全部綁定條件
成立時才存在。Consumer 必須把缺少 `app_id` 視為「沒有可用 binding」，不得從 `safe_ready` 推導。

新使用者 success 固定是以下形狀，不帶 Cookie、session token 或任何 SSO 欄位：

```ts
{ _res: "ok", status: "new", verify_token: string }
```

`verify_token` 有效 3600 秒，只可與同一 canonical alias 搭配 `reg_req`／`reg_choose_num`。

Endpoint-specific errors：

| `code` | 語意 |
|---|---|
| `safe_id 不能用於驗證碼登入` | `id` 被分類為 Safe ID。 |
| `too_many_attempts` | alias＋IP 在比較前原子計數，第 7 次鎖該組 3600 秒；其他 IP 不受該鎖影響。 |
| `verification_code_error` | 驗證碼不相符、過期、已消費或尚在交付。 |
| `user_404` | Alias row 存在但權威 user row 已不存在；fail closed。 |

每次嘗試將計數期限延後 3600 秒；常數時間比較後 CAS 消費，並行正確請求只有一個成功。
IPv4 映射位址先還原；IPv6 同一 /64 共用猜碼及鎖定額度，其他 IPv4／IPv6 /64 不受此鎖影響。
CAS 同時核對傳送世代，固定碼跨輪重複時舊讀取不能刪新碼。R1 使用 HMAC 索引與
`h1.k<curr>.` 命名空間，不讀取部署前以明文別名索引的舊碼；使用者須重新申請。
失敗不發 session 或註冊 token；成功只清自己仍相符的計數，不抹掉並行嘗試。

另有「每組驗證碼」的猜測上限，與來源 IP 無關：同一組已發出的驗證碼累計被比較超過 20 次（含錯誤與
並行嘗試）即作廢，之後不論輸入是否正確都回 `too_many_attempts`，須重新申請驗證碼；重新發碼會把計數歸零。
這是因為 alias＋IP 的鎖定只擋單一來源，換 IP 的分散式猜碼要由驗證碼本身的總量上限收斂。

## 5. `POST /web/reg_req`

為通過 `alias_verify` 的新使用者取得候選 Safe ID。

```ts
type RegRequest = {
  id: string,
  verify_token: string,
}

type RegRequestSuccess = {
  _res: "ok",
  avail_safe_ids: string[],
}
```

`avail_safe_ids` 只包含目前為此 canonical alias 的 HMAC 預留的候選值，最多三個；consumer 不得假設固定數量。
預留與註冊均以資料庫交易為權威。`verify_token` 內只儲存派生資料，不儲存完整別名；
缺少派生欄位或 key version 過期時要求重新驗證，不讀取舊明文 token。

| `code` | 語意 |
|---|---|
| `safe_id 不能用於註冊` | `id` 被分類為 Safe ID。 |
| `token_expired` | Token 不存在或已過期。 |
| `token_alias_mismatch` | Token 的 canonical alias 與 `id` 不符。 |
| `registered_already` | Alias 已由其他流程完成註冊。 |

## 6. `POST /web/reg_choose_num`

選擇已預留的 Safe ID 並完成註冊。SSO caller 必須原樣重送 `alias_verify` 的三個 context 欄位。

```ts
type RegChooseRequest = {
  id: string,
  verify_token: string,
  safe_id: string,
  nickname?: string, // 省略或 exact 空字串時使用 safe_id；非空值原樣儲存且最多 50 Unicode code points
  app_tag?: string,
  sign_pk?: string,
  enc_pk?: string,
}
```

Success 會新建 session token（簽發語意與 `alias_verify` 相同，不簽發 Cookie，結果無法確認時回
`session_issue_failed`）；沒有 `status` 欄位：

```ts
type RegChooseSuccess =
  | { _res: "ok", safe_id: string, nickname: string, token: string }
  | {
      _res: "ok", safe_id: string, nickname: string, token: string,
      safe_ready: false, app_id?: string,
    }
```

第二個 variant 只在 Web SSO context 使用。新註冊 user 沒有 Safe encryption key，所以
`safe_ready` 固定為 `false`。有效的非 AppData 服務可以建立純 SSO binding 並回傳 `app_id`；AppData
服務不會在此建立 binding，因此不回傳 `app_id`。無論是否回傳 `app_id`，都適用第 2 節的禁止自動
cleanup 規則。

| `code` | 語意 |
|---|---|
| `safe_id 不能用於註冊` | `id` 被分類為 Safe ID。 |
| `token_expired` | Token 不存在或已過期。 |
| `token_alias_mismatch` | Token 的 canonical alias 與 `id` 不符。 |
| `number_gone` | 候選號碼已不存在。 |
| `wrong_reservation` | 候選號碼不是為此 alias 預留。 |
| `registered_already` | Alias 已由其他流程完成註冊。 |
| `session_issue_failed` | 帳號已註冊，但 session 簽發的提交結果無法確認；不回傳 token，請重新登入。 |

## 7. `POST /web/user_update`

同時提供 `safe_id + token` 更新 nickname。`/web/*` 是 BE-to-BE 介面，只認這一組憑證：
不簽發、不讀取、不清除任何 Cookie（`web_sid`、舊制 `web_uid` 都被忽略），也不做同源檢查。
SSO 的 `uid`／`sso_session` 不授權此介面。

遷移說明：先前版本簽發的 `web_sid` Cookie 不再被採信；瀏覽器端沒有 HttpOnly 保護的 `token` 不得放進前端，
只可由第三方後端持有。既有 session 列沿用，不需要資料庫遷移，持有 token 的後端不必重新登入。

Session 的真相是伺服器端 `sso_tokens` 的一列，BE-to-BE `token` 指向該列：

- 絕對有效期 30 天：自簽發起算，使用再頻繁也不延長。
- 閒置有效期約 7 天：每次通過授權的請求會更新閒置計時，但更新有最長 1 小時的節流，所以實際閒置上限為 7 天加最多 1 小時。
- 過期、已登出或不存在的 session 一律回 `not_logged_in`，列由背景清掃回收。
- 驗證本身不更新閒置計時；只有授權通過之後才更新。被拒絕的請求不延長 session。

```ts
type UserUpdateRequest = {
  nickname: string, // trim 後必須為 1...50 UTF-8 bytes
  safe_id: string,
  token: string,
}

type UserUpdateSuccess = { _res: "ok", nickname: string }
```

持有仍有效的 `safe_id + token` 本身就是授權。`safe_id` 須為正的十進位 int32 canonical 字串，`token` 長度與字元集
須符合伺服器簽發的格式；格式不合、過期、已登出或不存在一律回 `not_logged_in`，且不觸達資料庫。
驗證通過才更新 session 閒置計時，再檢查 nickname。

Endpoint errors 是 `not_logged_in`、`nickname_required`、`nickname_too_long`。

## 8. `/web/logout`

登出使用 JSON：

```ts
type LogoutRequest = { safe_id: string, token: string }
type LogoutSuccess = { _res: "ok" }
```

`POST /web/logout` 是唯一方法：`GET` 路由已移除（回 405），避免任何他站圖片、連結或預取讓使用者被登出。
`safe_id` 與 `token` 兩欄必填（缺少時是標準缺參錯誤，屬 protocol failure）；格式不合回 `not_logged_in`。
格式正確時只刪除該 `(safe_id, token)` 這一列（同帳號其他 session 不受影響），無論原本是否存在都回上述 success
（冪等）。憑證本身就是授權，不做同源檢查，也不清除任何 Cookie、不跳轉。

SSO 登出使用 golib 的 `/logout`，不受此介面影響。Endpoint error 是 `not_logged_in`。

本 endpoint 只清 9300 的 HTTP session/token，不會代替 9305 KPS `app_logout`。普通 KL SSO
登出必須在仍持有目前 `sign_sk` 時先呼叫 `app_logout`，成功後刪除 signing credential 並保留
`enc_sk/enc_pk`；下次登入才可用同一 encryption identity 與新 signing credential 認回原
`app_id`。永久斷開及刪除最後 AppData reference 才使用 `app_del`。

## 9. 建議流程

```text
alias_ping {id, send_code:true}
  -> alias_verify {id, code, optional SSO context}
     -> status=existed: 建立第三方 session
     -> status=new:
        reg_req {id, verify_token}
        -> reg_choose_num {id, verify_token, safe_id, nickname?, optional SSO context}
```

每一步都重新檢查 `_res` 與 exact variant。`app_id` 缺失時停止 AppData 自動復原；callback、finish、
本機 session 儲存或 AppData 操作失敗時只清理 consumer 自己的 pending/session，不撤銷 KeyLockr binding。
