connectbase-client 6.11.0 → 6.13.0

package/CHANGELOG.md

@@ -3,6 +3,131 @@
 본 SDK 의 모든 주요 변경사항을 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 형식으로 기록합니다.
 버전은 [Semantic Versioning](https://semver.org/lang/ko/) 을 따릅니다.
 
+## [6.13.0] - 2026-11-11
+
+### Security — WebRTC 역할과 룸 인가를 서버가 정한 대로 따른다
+
+- `cb.webrtc.connect({ allowedMemberIds })`(REST `joinRoom` 의 `allowed_member_ids`)를 더한다. 이 연결이 룸을 새로 열면
+  목록의 회원과 자신만 들어오는 비공개 룸이 된다(로그인 회원만, 최대 50명). 목록 밖 회원과 익명은 들어오지도, 룸 목록과
+  참가자 조회로 보지도 못한다. 이미 공개 룸으로 열린 같은 ID 에 목록을 들고 오면 들어가지 않고 오류로 끝난다.
+  `cb.webrtc.isPrivateRoom()` 으로 확인한다. `switchRoom()` 은 이 목록을 이어받지 않는다.
+- `cb.webrtc.isBroadcaster()` 를 더한다. `joined` 의 `is_broadcaster`(서버가 정한 역할)를 돌려준다. 요청(`isBroadcaster: true`)과
+  다를 수 있다 — 익명 연결, 채널 방송자 역할(`publisher_roles`)이 없는 회원은 시청자다.
+- `cb.webrtc.onWarning(({ code, message }) => ...)` 를 더한다. 서버가 요청을 바꾼 이유(`broadcaster_requires_auth`,
+  `broadcaster_role_required`, `quota_check_degraded`)가 온다. 예전에는 버려졌다.
+- join 메시지에 `user_id` 를 싣지 않는다. 서버는 2026-11-08 부터 읽지 않았다(참가자 신원은 인증 정보에서 온다).
+  `connect({ userId })` 는 SDK 안에서만 쓰는 값으로 남는다.
+
+### Fixed — WebRTC 오류 문구, 서버에 없는 필드
+
+- 할당량, 동시접속 초과처럼 `{ error, message }` 객체로 오는 시그널링 `error` 가 `Unknown error` 로 바뀌던 것을 고쳐
+  `message` 를 그대로 전한다.
+- `PeerInfo.joined_at` 을 뺀다. 서버가 보낸 적이 없는 필드였다(늘 `undefined`).
+- `RoomSummary.private`, `JoinRoomResponse.private`, `JoinRoomRequest.allowed_member_ids` 타입을 서버 응답에 맞춰 더한다.
+
+### Security — 구독 금액도 서버의 가격표가 정한다
+
+- `cb.subscription.create({ product_id })` 형태를 더한다. 콘솔 가격표의 **정기 상품**(주기가 있는 상품)으로 구독하면
+  금액, 통화, 주기, 플랜명, 무료 체험, MoR PG 가격 ref 를 서버가 상품에서 정하고, 첫 청구는 기본으로 즉시다.
+  `changePlan(id, { product_id })`, `previewChangePlan`, `chargeWithBillingKey({ product_id, quantity })`,
+  `update(id, { product_id })`(서버 호출만)도 같다.
+- 금액을 직접 보내는 기존 형태는 그대로 동작한다. 다만 서버는 결제 설정의 금액 출처가 `client`(레거시)인 앱이거나 서버 호출
+  (시크릿 키, service_role 함수)일 때만 받는다. 가격표 전용(`catalog`) 앱의 브라우저 호출에서는:
+  - 금액 지정 403 `client_amount_not_allowed`, `start_now: false` 와 `billing_day` 403 `client_schedule_not_allowed`
+  - `update()` 로 금액, 플랜명, 상품 변경 403 `client_plan_change_not_allowed`
+  - `changePlan()` 에 `provider_price_ref` 직접 지정 403, 지금 정산하지 않는 `proration_mode` 와 `on_payment_failure:
+    'apply_change'` 403 `proration_mode_not_allowed`
+- 요청 타입을 유니온으로 나눴다(`CreateSubscriptionWithProduct | CreateSubscriptionWithAmount`,
+  `ChangePlanWithProduct | ChangePlanWithPriceRef`, `ChargeWithBillingKeyProduct | ChargeWithBillingKeyAmount`). 두 형태를
+  섞으면 컴파일 에러다(서버도 400 `product_with_amount_fields`).
+- `SubscriptionResponse.product_id` 를 더한다. 권한은 `metadata` 가 아니라 이 값으로 지급한다. 서버가 금액을 직접 바꾸거나
+  PG 가 가격표에 없는 가격으로 바꾸면 비워진다. `chargeWithBillingKey()` 응답에 `currency`, `product_id`, `quantity` 가 온다.
+- 새 오류 코드: `product_not_recurring`, `product_is_recurring`(정기 상품을 `payment.prepare` 에 넘김),
+  `product_price_ref_missing`(MoR 구독에 쓸 PG 가격 ref 가 상품에 없음), `subscription_amount_update_unsupported`
+  (PG 가 청구 금액을 정하는 구독의 금액만 변경), `order_id_conflict`(같은 `order_id` 를 다른 금액이나 상품으로 재시도),
+  `subscription_amount_mismatch`(첫 청구 승인 금액 불일치).
+
+## [6.12.0] - 2026-11-11
+
+### Changed — 세션이 없다는 것을 이미 알면 `getMe()` 가 서버에 묻지 않는다
+
+- 메모리에 토큰이 없고 60초 안의 쿠키 복구가 "세션 없음"(401 또는 quiet 204)으로 끝났으면, `cb.auth.getMe()` 는 요청 없이
+  서버가 주는 것과 같은 401 `ApiError` 를 던진다. 반환과 오류 계약은 그대로이고, 로그인 안 한 방문자에게 매 페이지
+  「Failed to load resource 401」(`/v1/public/app-members/me`)이 남던 것만 사라진다.
+
+### Security — 소셜 로그인 콜백은 세션을 만들지 않는다. 이 브라우저에서 시작한 로그인임을 확인한 교환만 만든다
+
+6.11.0 은 남이 보낸 콜백 링크의 URL 토큰과 `code` 를 거부했지만, 서버가 콜백 응답에서 이미 refresh 쿠키를 심은 뒤였다.
+공격자가 자기 계정으로 시작해 멈춰 둔 프로바이더 콜백 링크(`/v1/public/oauth/<provider>/callback?code=&state=`)를 피해자가
+열면, SDK 가 결과를 거부해도 다음 페이지에서 그 쿠키로 공격자 세션이 복구됐다(로그인 CSRF).
+
+- `cb.oauth.signIn()` / `signUp()` / `signInWithPopup()`(네이티브 브릿지 포함)이 인가 요청에 `response_type=code` 를 싣는다.
+  서버는 그 흐름의 콜백에 토큰 대신 1회용 `code` 만 싣고 쿠키를 심지 않는다. 세션 쿠키는 SDK 가 state 를 확인한 뒤 부르는
+  `POST /v1/auth/oauth/exchange` 응답이 심는다(서버는 그 앱 소유 origin 의 요청에만 심는다).
+- `getCallbackResult()` 와 부팅 안전망(`new ConnectBase()`)이 `?code=&state=` 콜백을 처리한다. state 가 이 브라우저에서
+  만든 값이면 교환해 토큰을 저장하고 결과는 예전과 같은 모양(`access_token`, `refresh_token`, `member_id`, `is_new_member`,
+  `email`, `state`)이다. 콜백 페이지에서 `getCallbackResult()` 만 부르던 앱은 코드를 바꿀 필요가 없다. `code` 를 한 번만
+  교환하므로 `exchangeCodeFromCallback() ?? getCallbackResult()` 패턴도 그대로 동작한다.
+- state 가 맞지 않는 `code` 는 교환하지 않는다. `getCallbackResult()` 는 이제 `null` 대신 `{ error: 'oauth_state_mismatch' }`
+  를 돌려주고, 주소의 `code` 는 건드리지 않는다(앱 자체 OAuth 의 `code` 일 수 있다). 부팅 때는 그런 `code` 를 손대지 않는다.
+- 앱이 지정한 팝업 콜백 페이지(`signInWithPopup(provider, callbackUrl)`)도 `code` 를 받는다. 그 페이지의 `getCallbackResult()`
+  가 교환해 같은 출처 opener 에게 넘기고 창을 닫는다.
+- 네이티브 브릿지 팝업(`signInWithPopup` 이 패키징 앱에서 외부 브라우저로 가는 경로)도 일회용 state 를 보내고, 돌아온 주소의
+  state 가 맞을 때만 결과를 받는다. 같은 스킴으로 열린 남의 주소가 결과로 넘어와도 로그인되지 않는다.
+- 서버가 `response_type` 을 모르면(옛 서버) 예전처럼 URL 토큰을 받아 처리한다. 서버와 SDK 의 배포 순서는 상관없다.
+
+### Security — 결제 금액은 서버의 가격표가 정한다
+
+- `cb.payment.prepare({ product_id, quantity })` 형태를 더한다. 콘솔(결제 설정 > 가격표)에 등록한 상품의 단가 x 수량과
+  통화를 **서버가** 계산한다. 브라우저에서 `amount` 를 보내면 사용자가 개발자 도구로 10,000원 상품을 1원으로 고쳐 결제할
+  수 있었다. `createCheckoutSession({ product_id, quantity, ... })` 도 같다.
+- 금액을 직접 보내는 기존 형태(`amount` + `order_name`)는 그대로 동작한다. 다만 서버는 결제 설정의 금액 출처가
+  `client`(레거시, 기존 앱의 기본값)인 앱이거나 서버 호출(시크릿 키, service_role 함수)일 때만 받는다. 새 앱은
+  `catalog` 로 시작하고, 이 앱에서 브라우저가 금액을 보내면 403 `client_amount_not_allowed` 다.
+- 두 형태를 섞으면(`product_id` 와 `amount`/`order_name`) 컴파일 에러다(`PreparePaymentRequest` 는 이제
+  `PreparePaymentWithProduct | PreparePaymentWithAmount` 유니온이다). 서버도 400 `product_with_amount_fields` 로 거절한다.
+- 응답에 `currency`(결제 금액의 통화)와 `product_id`, `quantity` 를 싣는다. `confirm()` 응답에도 `currency` 가 오고,
+  `getByOrderId()`/`list()` 결과에도 `product_id`, `quantity` 가 온다. 권한 지급은 `metadata`(클라이언트 값)가 아니라
+  이 두 값으로 한다.
+- 새 오류 코드: `payment_product_not_found`(404), `payment_product_inactive`(409), `product_with_amount_fields`,
+  `product_or_amount_required`, `quantity_requires_product`, `payment_amount_too_large`, `currency_not_supported`(400,
+  toss 와 payapp 은 KRW 상품만), `client_amount_not_allowed`(403).
+
+### Added — 로그인 멤버의 실시간 연결이 만료 전에 토큰을 갱신한다 (`cb.realtime`, `cb.database` 실시간)
+
+- 서버(socket-server, data-server)가 멤버 토큰 연결의 만료를 집행한다. 연결 토큰이 이 SDK 가 로그인으로 들고 있는 멤버
+  세션(같은 앱, 같은 멤버)의 것이면 SDK 가 `token_refresh=1` 로 협상하고, 서버가 만료 5분 전에 보내는 `token_expiring`
+  (또는 `token_expired`)에 맞춰 HTTP 요청과 같은 refresh(같은 single-flight, 같은 실패 처리)로 새 토큰을 받아 연결 위에서
+  바꾼다(`auth_refresh`). 구독, 프레전스, DB 스냅샷을 다시 받지 않는다. 실패하면 30초마다 다시 해 본다.
+- 재연결은 붙기 전에 토큰을 확인해, SDK 세션의 토큰이 1분 안에 만료되면 새로 받아 붙는다(끊긴 사이 만료된 토큰으로
+  재연결이 거부되던 문제). 갱신한 토큰은 이후 재연결에도 쓴다. `connectRealtime()` 은 넘긴 옵션 객체를 고치지 않는다.
+- 갱신할 수 없는 토큰(다른 곳에서 받은 토큰, 함수 런타임의 위임 토큰, cross-app OAuth 토큰)은 협상하지 않는다 — 예전과
+  같이 서버가 만료 24시간 뒤에 닫는다(`code: 'token_expired'`, close 4401).
+- `HttpClient` 에 `canRefreshMemberToken(token)`, `freshTokenForMember(token, minValiditySec, { replace? })` 를 더했다
+  (실시간 클라이언트가 쓰는 내부용 공개 메서드).
+
+### Changed — 멤버 폐기와 토큰 만료로 닫힐 때의 알림
+
+- 서버가 멤버를 정지, 삭제하거나 세션을 모두 끊으면(강제 로그아웃, `signOut()` — 모든 기기 로그아웃, 비밀번호 변경과
+  재설정) 그 멤버의 실시간 연결을 바로 닫는다(close 4403 `member_revoked`). 닫기 직전의 서버 안내(`MEMBER_REVOKED`,
+  `TOKEN_EXPIRED`)를 따로 `onError` 로 보내지 않고, 이어지는 close 의 `RealtimeConnectionError` 메시지로 한 번만 알린다.
+- `cb.realtime`: 토큰 만료(4401)로 닫혔는데 SDK 세션이 살아 있으면 새 토큰으로 다시 붙는다. 멤버 폐기(4403)는 다시 붙지
+  않는다.
+- `cb.database` 실시간: 멤버 폐기(4403)와 갱신할 수 없는 토큰의 만료(4401)는 재연결하지 않고 `onRealtimeError` 로
+  `RealtimeConnectionError`(`code: 'member_revoked'` / `'token_expired'`)를 알린다. 예전에는 같은 토큰으로 다섯 번 재연결한
+  뒤 "Max retries exceeded" 로 끝났다. 그 밖의 끊김은 예전처럼 다시 붙는다.
+
+### Added — `ctx.cbAdmin.appMembers.suspend()` / `unsuspend()` (management_scope `app_member:suspend`)
+
+- service_role 함수가 회원을 정지하고 푼다. 신고 처리, 스팸이나 결제 사기 자동 제재처럼 되돌릴 수 있는 차단을 함수로 만들 때
+  쓴다. 함수의 `management_scopes` 에 `app_member:suspend` 를 넣어야 하고, 위임하는 사람에게는 콘솔의 `app_member:write` 가
+  필요하다. 삭제(`app_member:write`)와는 서로 함의하지 않는다.
+- `suspend(appId, memberId, { reason, until? })`: `reason`(1~500자, 정지된 회원에게 보이는 문구)은 필수이고, `until`
+  (`Date` 또는 ISO 문자열)을 생략하면 `unsuspend` 할 때까지 영구 정지다. 콘솔의 정지와 같이 그 회원의 세션을 모두 끊고
+  붙어 있는 실시간 연결을 닫는다(`member_revoked`).
+- `unsuspend(appId, memberId)`: 정지를 푼다. 끊긴 세션은 되살아나지 않는다(회원은 다시 로그인한다).
+- 함수 런타임은 배포 때 최신 SDK 를 설치하므로, 이 판이 나온 뒤 함수를 다시 배포하면 쓸 수 있다.
+
 ## [6.11.0] - 2026-11-11
 
 ### Security — CLI 브라우저 로그인은 터미널의 사용자 코드로 승인한다

package/README.md

@@ -1000,6 +1000,21 @@ await subscription.unsubscribe()
 await cb.realtime.disconnect()
 ```
 
+#### 로그인 멤버 연결의 토큰 갱신과 멤버 폐기 (Unreleased)
+
+`cb.realtime.connect({ accessToken })` 과 `cb.database.connectRealtime({ accessToken })` 에 넘긴 토큰이 SDK 가 로그인으로
+들고 있는 멤버 세션(같은 앱, 같은 멤버)의 것이면, SDK 가 만료 전에 HTTP 요청과 같은 refresh 로 새 토큰을 받아 **연결을 끊지
+않고** 바꿉니다(서버와 `token_refresh=1` 로 협상, `auth_refresh`). 재연결도 새 토큰을 씁니다. 앱이 할 일은 없습니다.
+
+| 상황 | 결과 (`onError` / `onRealtimeError`) |
+|---|---|
+| 갱신할 수 없는 토큰(다른 곳에서 받은 토큰, 위임 토큰)이 만료되고 24시간 지남 | `RealtimeConnectionError`, `code: 'token_expired'`(close 4401). 재연결하지 않음 — 새 토큰으로 다시 연결 |
+| SDK 세션이 끝나 갱신 실패(로그아웃, refresh 거부) | 만료 5분 뒤 같은 `token_expired` |
+| 멤버 정지, 삭제, 세션 전체 종료(강제 로그아웃, `signOut()`, 비밀번호 변경) | `code: 'member_revoked'`(close 4403), 메시지는 서버 안내. 재연결하지 않음 — 다시 로그인 |
+
+로그아웃 버튼에서는 `cb.realtime.disconnect()` (DB 실시간은 `cb.database.disconnectRealtime()`)를 `cb.auth.signOut()` 보다
+먼저 부르면 `member_revoked` 알림 없이 끝납니다 — `signOut()` 은 모든 기기의 세션을 끊어 서버가 그 멤버의 연결을 닫습니다.
+
 #### Who sent it: `fromMember` (v6.7.0)
 
 `message.from` 은 보낸 연결이 접속할 때 스스로 정해 보내는 `client_id` 라 누구나 다른 값을 흉내 낼 수 있습니다. 서버가 검증한
@@ -1471,7 +1486,14 @@ cb.webrtc.onRemoteStream((peerId, remoteStream) => {
   videoElement.srcObject = remoteStream
 })
 
-// 룸 전환 (생략한 옵션은 현재 세션 값을 이어받습니다)
+// 역할은 서버가 정한다 — 익명 연결이나 채널 방송자 역할(publisher_roles)이 없는 회원은 시청자
+cb.webrtc.onWarning(({ code, message }) => console.warn(code, message))
+console.log(cb.webrtc.isBroadcaster())
+
+// 비공개 룸 (로그인 회원) — 목록의 회원만 들어오고 볼 수 있다. 참가자 모두 같은 목록을 보낸다
+await cb.webrtc.connect({ roomId: `call:${callId}`, allowedMemberIds: [aliceId, bobId], localStream: stream })
+
+// 룸 전환 (생략한 옵션은 현재 세션 값을 이어받습니다. allowedMemberIds 는 이어받지 않습니다)
 await cb.webrtc.switchRoom('live:room-2')
 
 // 연결 해제
@@ -1660,6 +1682,8 @@ await cb.support.reportIssue({
 | 스코프 | 열리는 메서드 |
 |---|---|
 | `app_member:read` | `appMembers.list` / `appMembers.get` — 멤버 목록·상세 (**이메일 포함**) |
+| `app_member:write` | `appMembers.remove` — 멤버 삭제 (되돌릴 수 없음) |
+| `app_member:suspend` | `appMembers.suspend(appId, memberId, { reason, until? })` / `appMembers.unsuspend` — 정지와 해제 (세션 종료, 실시간 연결 끊기 포함. `until` 생략 시 영구) |
 | `role:read` | `roles.list` / `roles.get` |
 | `role:manage` | `roles.create` / `roles.update` / `roles.assign` / `roles.delete` |
 | `payment:read` | `payment.list` — 결제 내역 |
@@ -1691,7 +1715,7 @@ export async function handler(payload, ctx) {
 
 `appMembers.list` 의 `email` 은 `app_members.email` 컬럼이 우선이고, 비어 있으면 `EMAIL` identity 의 `provider_uid` 로 fallback 한다. 소셜 제공자가 이메일을 주지 않은 회원은 빈 문자열이다. `total_count` 는 `search` 필터를 반영하므로 페이지네이션에 그대로 쓸 수 있다.
 
-**멤버가 자기 정보를 볼 때는 `cb.auth.getMe()` 를 쓴다.** `appMembers.*` 는 운영자 방향 조회 전용이고, 멤버 쓰기(생성·삭제·정지·수정)는 콘솔 전용이라 `app_member:read` 로 열리지 않는다.
+**멤버가 자기 정보를 볼 때는 `cb.auth.getMe()` 를 쓴다.** `appMembers.list/get` 은 운영자 방향 조회이고, 삭제(`app_member:write`)와 정지(`app_member:suspend`)는 각자의 스코프가 따로 필요하다 — `app_member:read` 로는 열리지 않는다. 생성과 수정은 콘솔 전용이다.
 
 ```typescript
 // 역할(RBAC) 관리 — management_scopes: ["role:read", "role:manage"]

package/dist/cli.js

@@ -170,7 +170,7 @@ function handleTunnelError(msg, appId, localPort) {
 }
 
 // src/cli.ts
-var VERSION = "6.11.0" ? "6.11.0" : getPackageVersion();
+var VERSION = "6.13.0" ? "6.13.0" : getPackageVersion();
 var DEFAULT_BASE_URL = "https://api.connectbase.world";
 var colors = {
   reset: "\x1B[0m",