# 獨立遊戲業務後台驗證 API

NBTiktok 負責帳號驗證與短效 JWT 簽發，遊戲用戶端負責路由。本機、測試與正式後台使用相同的 `credentials.gameBackend` 合同、Audience 與 JWKS 驗證器。

## 用戶端流程

| 項目 | 合同 |
| --- | --- |
| Backend JWT | `credentials.gameBackend` |
| 公開金鑰 | `/.well-known/game-backend-jwks.json` |
| 資料身份 | `(gameId, space, sub)` |

呼叫 `POST /api/game-client/v2/login` 時只傳 Email、密碼、`gameId`、`mode` 與 `clientBuild`。啟用獨立後台後，回應包含不帶 URL 的 `backendAuth`，以及最長 30 分鐘的 Ed25519 `credentials.gameBackend`。

HTTP 與 WebSocket URL 分別來自可信 build 設定；本機可使用 `NBT_GAME_BACKEND_HTTP_URL=http://127.0.0.1:19101` 與 `NBT_GAME_BACKEND_WS_URL=ws://127.0.0.1:19101/ws`。明文只允許 localhost、`127.0.0.0/8` 或 `[::1]`；遠端測試及正式環境必須使用 HTTPS/WSS。不得把 URL 上傳 NBTiktok，也不得在跨 Origin 重新導向時攜帶 Bearer。

後台透過 [`/.well-known/game-backend-jwks.json`](/.well-known/game-backend-jwks.json) 驗證簽章、`kid`、Issuer、精確 Audience、`gameId`、`scope=game.session`、`space`、`sub`、`account`、`iat/nbf/exp` 與最長生命週期。資料鍵使用 `(gameId, space, sub)`，Sandbox 與 Production 必須隔離。

Node SDK `@nbtiktok/game-backend-auth` 0.4.x 提供 `createVerifier`，同一設定可部署到所有環境，並拒絕超過 1,800 秒的 Token。

## 獨立後台 WebSocket

此 WebSocket 與平台事件端點 `/ws/game-client/v2` 完全分離：獨立後台使用 `credentials.gameBackend.token`，平台端點仍使用一次性 `credentials.websocket.ticket`，兩者不得混用。

以固定子協定 `nbt.game-backend.v1` 連線可信後台 URL。Token 不得放入 URL、Cookie 或子協定；連線後五秒內傳送不超過 20 KiB 的文字幀：

```json
{"type":"nbt.auth","token":"<credentials.gameBackend.token>"}
```

後台把原始文字交給 SDK `verifyWebSocketAuthFrame(text, verifier, currentClaims?)`，成功取得 Claims 與安全 ACK：

```json
{"type":"nbt.auth.ok","expiresAt":"2026-09-02T12:30:00.000Z"}
```

平台 Session refresh 回傳新 Backend JWT 後，在原連線再次傳送同一 `nbt.auth`。續簽要求 `gameId`、`space`、`sub`、`sid` 不變，再原子更新帳號快照、設定版本與到期時間。初次驗證前或排序中的續簽幀尚未完成時不得處理後續業務幀；已安裝 JWT 到期時必須關閉。

缺失、無效或過期驗證使用關閉碼 `4401`，身份改變使用 `4403`，驗證逾時 `4408`，幀過大 `1009`，JWKS 暫不可用 `1013`。日誌遮蔽 Authorization 與 `token`；瀏覽器部署還要精確限制 Origin，沒有 Origin 的原生用戶端仍須 JWT 驗證。

倉庫中的可執行 `examples/independent-game-backend` 提供 loopback HTTP Bearer、WebSocket 首幀驗證、原連線續簽、瀏覽器與 Node 用戶端。

## 瀏覽器 Portal

第三方網站建立 `state` 與 S256 PKCE 後開啟 `/game-portal/authorize`。使用者只在 NBTiktok 官方頁面重新輸入 Email 密碼。回呼取得 60 秒一次性 Code；後台呼叫 `POST /api/game-portal/v2/token` 兌換並以 Portal JWKS 驗證 `portalToken`。

Production 使用精確登記的 HTTPS 回呼。本機只允許 `http://127.0.0.1:<port>/__nbt/callback` 或 IPv6 loopback。SDK 提供 `createPortalAuthorizationRequest`、`exchangePortalCode` 與 `createPortalVerifier`。

驗證後由第三方自行建立 HttpOnly、Secure、SameSite=Lax Cookie，最長八小時且不得超過 `authorizationExpiresAt`。NBTiktok 不代理業務請求，也不管理第三方 Cookie。