connectbase-client 3.7.2 → 3.8.1

package/CHANGELOG.md

@@ -3,6 +3,162 @@
 본 SDK 의 모든 주요 변경사항을 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 형식으로 기록합니다.
 버전은 [Semantic Versioning](https://semver.org/lang/ko/) 을 따릅니다.
 
+## [3.8.1] - 2026-05-07
+
+### Fixed — `/v1/auth/re-issue` 가 콘솔/SDK cookie 공존 시 잘못된 토큰 발급
+
+3.8.0 의 cookie 우선순위가 [member → user → Bearer] 로 고정되어, 같은 브라우저에
+platform 콘솔용 `refresh_token` 과 SDK 용 `cb_member_refresh_token` 이 공존할 때
+(예: 외부 앱 SDK 로그인 후 콘솔 로그인) 콘솔의 `/v1/auth/re-issue` 호출이
+AppMember access token 을 받아 콘솔 측 endpoint(예: `/v1/cli-auth/approve/:id`,
+`claims.UserID == nil`) 에서 401 발생하던 회귀를 수정했습니다.
+
+- SDK 의 `refreshAccessToken()` 이 `/v1/auth/re-issue` 호출 시 `X-Public-Key` 헤더를
+  첨부합니다. 백엔드는 이 헤더로 SDK 호출(member cookie 우선) vs 콘솔 호출
+  (user cookie 우선) 을 식별합니다.
+- 백엔드 `auth_controller.ReIssueAccessToken` 우선순위:
+  1. `Authorization: Bearer` (가장 명시적)
+  2. cookie 단독 시 X-Public-Key 헤더 유무로 분기
+- Bearer 흐름 / 단일 cookie 흐름은 영향 없음. 회귀 시나리오만 정상화.
+
+3.8.0 사용자는 3.8.1 로 업데이트하면 됩니다. 백엔드 측은 함께 배포 필요.
+
+## [3.8.0] - 2026-05-07
+
+### Added — HttpOnly cookie 기반 refresh token 흐름 (XSS 면역 default 세션)
+
+3.7.x 의 `persistence` 콘솔 경고가 권고하던 "HttpOnly cookie + 기본값('none')" 흐름을
+실제로 동작하도록 SDK + 백엔드를 함께 구현했습니다.
+
+- `persistence: 'none'` (기본값) 으로도 **새로고침 후 자동 복구** 가능. refresh token 은
+  서버 HttpOnly cookie 로만 보관되어 JS 가 접근할 수 없습니다 (XSS 시 탈취 불가).
+- `localStorage` / `sessionStorage` 옵션은 여전히 사용 가능하지만 위험 경고가 유지됩니다.
+
+**SDK 변경:**
+
+- 모든 ConnectBase API fetch 호출에 `credentials: 'include'` 적용 — HttpOnly refresh cookie 가
+  자동 첨부됩니다 (`api.connectbase.world` host-only cookie 기준).
+- `/v1/auth/re-issue` 호출이 cookie 만으로 동작 — 메모리에 refresh token 이 없어도 cookie 가
+  있으면 access token 회복.
+- `ConnectBase` 옵션에 `autoRestoreSession?: boolean` 추가 (브라우저 기본 true). 인스턴스 생성
+  시 자동으로 cookie 기반 세션 복구를 시도하며, 미로그인/cookie 만료 시 silent 실패.
+- `cb.restoreSession(): Promise<boolean>` 메서드로 명시적 await 도 가능.
+- `persistence` 콘솔 경고를 갱신: 위험은 그대로 표시하되 'none' + HttpOnly cookie 흐름이
+  실제로 작동함을 안내.
+
+**백엔드 변경 (core-server):**
+
+- `pkg/util/cookie` 에 `CrossSite` / `HostOnly` 옵션 추가 (SameSite=None + Secure + host-only).
+- 새 공용 헬퍼 `core-server/app/util/auth_cookie/` — platform 용 `refresh_token` 과 AppMember/OAuth
+  용 `cb_member_refresh_token` 두 종류를 분리해 충돌 방지.
+- `/v1/public/app-members/{signin,signup,signout}` + `CreateGuestMember` + OAuth callback/exchange
+  엔드포인트가 refresh token 을 HttpOnly cookie 로 발급.
+- `/v1/auth/re-issue` 가 입력 우선순위 `[member cookie → user cookie → Authorization Bearer]`
+  로 처리하며, cookie 흐름은 sliding (재호출 시 cookie 만료 7일 연장).
+- 응답 body 의 `refresh_token` 은 하위호환을 위해 그대로 유지 (구버전 SDK / Node.js / 게임 SDK
+  호환). 신규 SDK 는 cookie 만 신뢰합니다.
+
+**마이그레이션:**
+
+기존 `persistence: 'sessionStorage'` 또는 `'localStorage'` 사용 중이었다면 옵션을 제거하기만
+하면 됩니다 (default 가 안전 흐름):
+
+```ts
+// before (3.7.x)
+new ConnectBase({ publicKey, persistence: 'sessionStorage' })
+
+// after (3.8.0)
+new ConnectBase({ publicKey })  // persistence: 'none' + autoRestoreSession: true (기본)
+```
+
+다른 origin 에서 호출하는 경우 (앱 도메인 ≠ `api.connectbase.world`) CORS 화이트리스트에 등록되어
+있어야 합니다 — 콘솔의 커스텀 도메인 등록 흐름이 그대로 적용됩니다.
+
+## [3.7.2] - 2026-05-01
+
+### Fixed — `cb.endpoint.connectWebSocket()` 메시지 깨짐 + permessage-deflate 누설
+
+3.7.0/3.7.1 의 endpoint WS pass-through 가 handshake 는 101 정상이지만 모든
+메시지가 binary frame 으로 도착하고 payload 가 origin (ComfyUI/aiohttp) 의
+raw WS frame bytes (RSV1=1 압축 frame 포함) 라 client 의 native WebSocket
+이 디코드 불가하던 문제를 수정했습니다. 두 개의 별개 버그가 합쳐진 회귀:
+
+1. **CLI 가 WS frame parse/encode 안 함** — 기존 `startWSStream` 이
+   `socket.on('data')` 의 raw bytes 를 그대로 v2 binary frame payload 로
+   forward 해서 client 에 frame header (0x81/0x82/0xc1) 가 섞인 상태로 도달.
+2. **`Sec-WebSocket-Extensions` 가 upstream 까지 forward 됨** — 브라우저 native
+   WebSocket 이 default 로 `permessage-deflate` 를 광고하고, sanitize 가 hop-by-hop
+   만 strip 해서 upstream (aiohttp default) 이 accept → compressed frame 송신
+   시작. CLI 는 deflate context 가 없어 디코드 불가.
+
+**Fix (CLI):**
+
+- `UpstreamWsFrameParser`: incoming WS frame 을 parse 해서 payload 만 추출.
+  TEXT/BINARY/CONTINUATION/PING/CLOSE 처리, fragmented frame 은 누적, RSV1
+  (compression) frame 은 protocol error 로 거부.
+- `buildClientFrame` / `createUpstreamTextFrame`: outgoing payload 를 RFC 6455
+  §5.3 client masking 적용한 masked WS frame 으로 encode 후 upstream 에 write.
+- 로컬 upstream 요청에서 `Sec-WebSocket-Extensions` 헤더 strip — proxy chain 이
+  deflate context 를 end-to-end 로 carry 하지 못하므로 compression 자체를 비활성.
+
+**회귀 영향 범위:** 3.7.0 의 모든 `cb.endpoint.connectWebSocket()` 사용자.
+ComfyUI / vLLM 등 default-on compression origin 영향. 사용자가 3.7.2 로 업그레이드
++ 터널 재시작 시 즉시 정상화. text/binary 구분은 client 측에서 항상 binary
+(ArrayBuffer) 로 도달 — JSON 은 `TextDecoder.decode` 로 string 변환 필요.
+Opcode propagation 은 별도 follow-up.
+
+**회귀 가드:** `UpstreamWsFrameParser` 단위 테스트 (TEXT payload 추출 / fragmented
+누적 / RSV1 reject / TCP coalescing / split-across-chunks / PING callback) +
+`buildClientFrame` masking round-trip + `WSStreamForwarder` e2e (real local HTTP
+server 로 `Sec-WebSocket-Extensions` 미도달 검증).
+
+## [3.7.1] - 2026-05-01
+
+### Fixed — `cb.endpoint.connectWebSocket()` 가 502 로 떨어지던 회귀
+
+3.7.0 의 endpoint WS pass-through 가 client 단에서 항상 CF 502 page 로 떨어지던
+문제를 수정했습니다. Root cause 는 CLI 가 로컬 upstream HTTP 요청에 WebSocket
+upgrade 헤더 (`Connection: Upgrade` + `Upgrade: websocket`) 를 누락한 것:
+upstream (ComfyUI 등) 이 일반 GET 으로 인식하고 400 Bad Request 반환 → core-server
+ReverseProxy 가 비-101 body 를 relay 하려다 `net/http: abort Handler` panic →
+CF 가 corrupted response 를 자체 502 page 로 substitute.
+
+**Primary fix (CLI):**
+
+- `cli.ts` `startWSStream` 과 `tunnel-v2.ts` `WSStreamForwarder` 가 upstream
+  요청에 `Connection: Upgrade` + `Upgrade: websocket` 명시적으로 set. tunnel-server
+  의 `sanitizeRequestHeaders` 가 RFC 7230 hop-by-hop 으로 strip 하므로 CLI →
+  upstream 새 hop 에서 다시 추가 필요.
+
+**Defensive fix (core-server, 자동 deploy):**
+
+- `ForwardWebSocket` `ModifyResponse` 에서 비-101 upstream 응답 시 ErrorHandler
+  경로로 라우팅 — ReverseProxy 가 비-101 body 를 relay 하려다 panic 하는 path
+  차단. Upstream 이 정당한 사유로 비-101 (rate limit / auth 실패 등) 반환할 때도
+  깨끗한 502 + 진단 메시지가 client 까지 도달.
+
+**회귀 영향 범위:** 3.7.0 의 모든 `cb.endpoint.connectWebSocket()` 사용자.
+사용자가 3.7.1 로 업그레이드 + 터널 재시작 시 정상 동작.
+
+**회귀 가드:** `tunnel-v2.test.ts` 가 `WSStreamForwarder` 의 upgrade 헤더 송신을
+real local HTTP server 로 e2e 검증. Go 측 `proxy_service_test.go
+TestForwardWebSocket_Non101UpstreamReturnsCleanError` 가 panic 없는 깨끗한 502
+반환을 락인.
+
+## [3.7.0] - 2026-05-01
+
+### Added — `cb.endpoint.connectWebSocket()` 네이티브 WebSocket 지원
+
+Endpoint Proxy v2 (Phase 5) 가 출하되어, SDK 사용자가 `cb.endpoint.connectWebSocket()`
+한 줄로 ComfyUI / vLLM / 일반 모델 서버의 WebSocket 엔드포인트를 직접 연결할 수
+있습니다. CLI 도 v2 endpoint (`/v2/tunnel/connect`) 를 사용하도록 전환.
+
+> **요구사항:** 백엔드 v2 endpoint 가 먼저 배포돼 있어야 동작합니다. 프로덕션
+> 배포 완료 후 SDK 업그레이드를 권장합니다.
+
+> **알려진 이슈:** 3.7.0 / 3.7.1 에서 WS frame leakage / 502 회귀가 발견되어
+> **3.7.2 이상 사용 권장**. 자세한 내용은 3.7.1 / 3.7.2 항목 참고.
+
 ## [3.6.0] - 2026-05-01
 
 ### Added — `cb.realtime.stream()` 멀티모달 메시지 (Vision) 지원
@@ -168,6 +324,38 @@ await cb.knowledge.search(kbId, {
 
 자세한 사용법: [docs/knowledge-base/USER_ISOLATION.md](https://github.com/connectbase-world/connectbase/blob/release/docs/knowledge-base/USER_ISOLATION.md)
 
+## [3.4.0] - 2026-04-30
+
+### Added — `cb.analytics.reset()` 사용자 전환 오염 방지 helper
+
+같은 브라우저에서 다른 사용자로 로그인할 때 방문자 (`visitor_uid`) 데이터가 이전
+사용자의 식별자에 묶인 채로 남아 데이터가 오염되던 문제를 SDK 측에서 끊어 낼 수
+있는 helper 를 추가했습니다.
+
+- **`cb.analytics.reset()`** — 로그아웃 시 호출. `visitor_uid` 를 새로 발급하고
+  in-flight 큐를 비웁니다.
+- **자동 reset (1) — `identify(memberId)` 가 다른 멤버 감지** — 직전 세션과 다른
+  `memberId` 가 들어오면 SDK 가 자동으로 `reset()` → identify 순으로 처리.
+- **자동 reset (2) — `linkMemberSilent` conflict 안전망** — 백엔드가 `409
+  VISITOR_LINKED_TO_OTHER_MEMBER` 응답을 주면 SDK 가 자동으로 reset 후 1회 재시도.
+  명시적 `reset()` 호출을 누락한 경우의 fallback.
+
+### Changed — BatchEvent 멱등성
+
+- 모든 `BatchEvent` 에 `event_id` (UUID) 자동 부여. 백엔드가 `(visitor_id,
+  event_id)` UNIQUE 인덱스 + `OnConflict DoNothing` 으로 at-least-once 재전송 시
+  중복 INSERT 차단. SDK 사용자 입장에서 추가 작업 없음.
+
+### Fixed — 첫 방문 봇 오판 방지
+
+- `flushSync` (`navigator.sendBeacon`) 호출에 `user_agent` 를 첨부 — 첫 방문 직후
+  `pagehide` 로 flush 될 때 백엔드가 UA 누락으로 봇으로 분류해 카운트가 누락되던
+  문제 해결.
+
+**서버 측 동시 변경:** `LinkMember` idempotent 처리, `WebPageView.event_id` 컬럼 +
+UNIQUE 인덱스, `link-member` 옵셔널 토큰 검증 (Authorization Bearer 가 있으면
+AppMember 토큰의 `member_id` 와 body 일치 검증, 없으면 BC 보존 + 경고 로그).
+
 ## [3.3.1] - 2026-04-30
 
 ### Fixed — Docs