獨立遊戲業務後台串接 API

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

#用戶端流程

呼叫 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 驗證簽章、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 的文字幀：

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

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

{"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。