connectbase-client 3.7.1 → 3.8.0

package/CHANGELOG.md

@@ -3,6 +3,142 @@
 본 SDK 의 모든 주요 변경사항을 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 형식으로 기록합니다.
 버전은 [Semantic Versioning](https://semver.org/lang/ko/) 을 따릅니다.
 
+## [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 +304,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

package/dist/cli.js

@@ -1456,6 +1456,129 @@ function createWsBinaryFrame(payload) {
   }
   return Buffer.concat([header, maskKey, masked]);
 }
+var UpstreamWsFrameParser = class {
+  constructor(handlers) {
+    this.buffer = Buffer.alloc(0);
+    this.fragmentBuffer = null;
+    this.h = handlers;
+  }
+  feed(chunk) {
+    this.buffer = Buffer.concat([this.buffer, chunk]);
+    try {
+      this.parse();
+    } catch (e) {
+      this.h.onError(e instanceof Error ? e : new Error(String(e)));
+    }
+  }
+  parse() {
+    while (this.buffer.length >= 2) {
+      const firstByte = this.buffer[0];
+      const secondByte = this.buffer[1];
+      const fin = (firstByte & 128) !== 0;
+      const rsv1 = (firstByte & 64) !== 0;
+      const opcode = firstByte & 15;
+      const isMasked = (secondByte & 128) !== 0;
+      let payloadLen = secondByte & 127;
+      let offset = 2;
+      if (payloadLen === 126) {
+        if (this.buffer.length < 4) return;
+        payloadLen = this.buffer.readUInt16BE(2);
+        offset = 4;
+      } else if (payloadLen === 127) {
+        if (this.buffer.length < 10) return;
+        const big = this.buffer.readBigUInt64BE(2);
+        if (big > BigInt(Number.MAX_SAFE_INTEGER)) {
+          throw new Error(`payload too large: ${big}`);
+        }
+        payloadLen = Number(big);
+        offset = 10;
+      }
+      let maskKey = null;
+      if (isMasked) {
+        if (this.buffer.length < offset + 4) return;
+        maskKey = this.buffer.subarray(offset, offset + 4);
+        offset += 4;
+      }
+      if (this.buffer.length < offset + payloadLen) return;
+      if (rsv1 && (opcode === 1 || opcode === 2 || opcode === 0)) {
+        throw new Error("upstream sent compressed (RSV1) frame without negotiation");
+      }
+      let payload = this.buffer.subarray(offset, offset + payloadLen);
+      if (maskKey) {
+        const unmasked = Buffer.alloc(payloadLen);
+        for (let i = 0; i < payloadLen; i++) {
+          unmasked[i] = payload[i] ^ maskKey[i % 4];
+        }
+        payload = unmasked;
+      }
+      this.buffer = this.buffer.subarray(offset + payloadLen);
+      const payloadCopy = Buffer.from(payload);
+      switch (opcode) {
+        case 0:
+          if (this.fragmentBuffer == null) {
+            throw new Error("continuation frame without preceding non-final data frame");
+          }
+          this.fragmentBuffer = Buffer.concat([this.fragmentBuffer, payloadCopy]);
+          if (fin) {
+            const out = this.fragmentBuffer;
+            this.fragmentBuffer = null;
+            this.h.onPayload(out);
+          }
+          break;
+        case 1:
+        // TEXT
+        case 2:
+          if (fin) {
+            this.h.onPayload(payloadCopy);
+          } else {
+            this.fragmentBuffer = payloadCopy;
+          }
+          break;
+        case 8:
+          this.h.onClose();
+          break;
+        case 9:
+          this.h.onPing(payloadCopy);
+          break;
+        case 10:
+          break;
+        default:
+          throw new Error(`unknown WS opcode 0x${opcode.toString(16)}`);
+      }
+    }
+  }
+};
+function createUpstreamTextFrame(payload) {
+  return buildClientFrame(129, payload);
+}
+function createUpstreamPongFrame(payload) {
+  return buildClientFrame(138, payload);
+}
+function buildClientFrame(firstByte, payload) {
+  const len = payload.length;
+  const maskKey = crypto.randomBytes(4);
+  let header;
+  if (len < 126) {
+    header = Buffer.alloc(2);
+    header[0] = firstByte;
+    header[1] = 128 | len;
+  } else if (len < 65536) {
+    header = Buffer.alloc(4);
+    header[0] = firstByte;
+    header[1] = 128 | 126;
+    header.writeUInt16BE(len, 2);
+  } else {
+    header = Buffer.alloc(10);
+    header[0] = firstByte;
+    header[1] = 128 | 127;
+    header.writeBigUInt64BE(BigInt(len), 2);
+  }
+  const masked = Buffer.alloc(len);
+  for (let i = 0; i < len; i++) {
+    masked[i] = payload[i] ^ maskKey[i % 4];
+  }
+  return Buffer.concat([header, maskKey, masked]);
+}
 var WsFrameParser = class {
   constructor(handlers) {
     this.buffer = Buffer.alloc(0);
@@ -1951,7 +2074,10 @@ ${colors.cyan}ConnectBase Tunnel${colors.reset}`);
     const fullPath = query ? `${reqPath}?${query}` : reqPath;
     const localHeaders = {};
     for (const [k, v] of Object.entries(headers)) {
-      if (k.toLowerCase() !== "host") localHeaders[k] = v;
+      const lk = k.toLowerCase();
+      if (lk === "host") continue;
+      if (lk === "sec-websocket-extensions") continue;
+      localHeaders[k] = v;
     }
     localHeaders["host"] = `localhost:${localPort}`;
     localHeaders["connection"] = "Upgrade";
@@ -1980,9 +2106,28 @@ ${colors.cyan}ConnectBase Tunnel${colors.reset}`);
         websocket: true
       });
       log(`${colors.dim}${(/* @__PURE__ */ new Date()).toLocaleTimeString()}${colors.reset} ${colors.cyan}WS${colors.reset} ${reqPath} \u2192 101`);
+      const upstreamParser = new UpstreamWsFrameParser({
+        onPayload: (payload) => {
+          if (cancelled) return;
+          sendBinary(sock, streamId, payload);
+        },
+        onPing: (payload) => {
+          if (cancelled || !upstream) return;
+          upstream.write(createUpstreamPongFrame(payload));
+        },
+        onClose: () => {
+          if (cancelled) return;
+          sendControl(sock, { type: "stream_close", stream_id: streamId });
+          streams.delete(streamId);
+        },
+        onError: (err) => {
+          sendControl(sock, { type: "stream_close", stream_id: streamId, error: `upstream_frame_error: ${err.message}` });
+          streams.delete(streamId);
+        }
+      });
       sk.on("data", (chunk) => {
         if (cancelled) return;
-        sendBinary(sock, streamId, chunk);
+        upstreamParser.feed(chunk);
       });
       sk.on("close", () => {
         if (cancelled) return;
@@ -2017,8 +2162,16 @@ ${colors.cyan}ConnectBase Tunnel${colors.reset}`);
     req.end();
     const forwarder = {
       kind: "ws",
+      // Encode the v2 payload as an upstream WS frame BEFORE writing to
+      // the socket. The prior implementation wrote raw payload to the
+      // socket which is not a valid WS frame; upstream WS servers (e.g.
+      // ComfyUI) would error out. Default to TEXT opcode — the v2
+      // protocol does not propagate the original opcode from the client,
+      // and most WS APIs (JSON-based) use text. Binary client→upstream
+      // is a known limitation pending opcode propagation in v2.
       feedBody: (chunk) => {
-        if (!cancelled && upstream) upstream.write(chunk);
+        if (cancelled || !upstream) return;
+        upstream.write(createUpstreamTextFrame(chunk));
       },
       endBody: () => {
       },