connectbase-client 3.25.1 → 3.26.0

package/CHANGELOG.md

@@ -3,6 +3,24 @@
 본 SDK 의 모든 주요 변경사항을 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 형식으로 기록합니다.
 버전은 [Semantic Versioning](https://semver.org/lang/ko/) 을 따릅니다.
 
+## [3.26.0] - 2026-05-28
+
+### Security — LLM provider API key 클라이언트 하드코딩 금지 명시화
+
+2026-05-28 vLLM API key 강화 작업 중 다수 정적 자산에 raw provider URL + API key 가
+하드코딩된 안티 패턴이 발견되어, SDK 표면에서 보안 정책을 명시한다. 동작 변경은 없다.
+
+- **`api/ai.ts`** — `AIAPI` 클래스 / `chat()` 메서드 JSDoc 에 보안 경고 + 안티 패턴/
+  베스트프랙티스 예시 추가. 클라이언트는 user public/secret key 만 사용하고, LLM
+  provider API key 는 콘솔 `AppAIConfig` 에 암호화 저장(서버 측만 복호화). `cb.ai.chat`
+  / `cb.ai.chatStream` 만 호출하면 서버 프록시가 tunnel `proxy_token` 자동 주입.
+  raw provider URL(`api.openai.com`, `tunnel.connectbase.world/<id>` 등) 직접 fetch 금지.
+- **`docs/18-sdk-ai.md`** — "🔒 보안 정책 (필수)" 섹션 신설(안티 패턴 / 베스트프랙티스 /
+  마이그레이션 절차). 영향 받은 앱은 cross_app_issue 로 개별 마이그레이션 알림 예정.
+
+본 버전은 런타임 동작 변경이 없는 문서/주석 강화이지만, 안티 패턴 차단을 SDK 표면에서
+명시화하는 정책 변경이므로 minor 로 올린다.
+
 ## [3.25.1] - 2026-05-27
 
 ### Fixed — 3.25.0 회귀 복구 + heartbeat 헬퍼 정리

package/dist/index.d.mts

@@ -7519,11 +7519,37 @@ interface AIStreamChunk {
  * })
  * ```
  */
+/**
+ * # 🔒 보안 — LLM API key 는 절대 클라이언트에 hardcode 금지
+ *
+ * 본 SDK 의 `chat` / `chatStream` 은 **ConnectBase 서버 프록시 경유** — provider (OpenAI/Claude/
+ * Gemini/Ollama/vLLM/...) API key 는 `AppAIConfig` 에 암호화 저장된 상태로 ConnectBase 가 server-side
+ * 에서만 복호화하여 사용합니다. 클라이언트는 user public key (또는 secret key) 만 알면 됩니다.
+ *
+ * **❌ 안티 패턴 — 즉시 다른 운영자에게 cross_app_issue 로 알려지고 차단됨**:
+ * ```ts
+ * // 브라우저 정적 자산에 raw provider URL + key — 절대 금지
+ * fetch("https://api.openai.com/v1/chat/completions", {
+ *     headers: { Authorization: "Bearer sk-..." }
+ * })
+ * // 또는
+ * fetch("https://tunnel.connectbase.world/<id>/v1/chat/completions", {
+ *     headers: { Authorization: "Bearer <vLLM key>" }
+ * })
+ * ```
+ * DevTools → Network 한 번이면 누구나 key 추출 → 추론 비용 폭주 / GPU 자원 고갈.
+ *
+ * **✅ 베스트프랙티스 — 본 SDK 호출만 사용**:
+ * ```ts
+ * await cb.ai.chatStream({ messages: [...], provider: "openai_compatible" }, callbacks)
+ * ```
+ */
 declare class AIAPI {
     private http;
     constructor(http: HttpClient);
     /**
-     * AI 채팅 (동기)
+     * AI 채팅 (동기). ConnectBase 서버 프록시 경유 — provider API key 는 server-side `AppAIConfig`
+     * 에서만 사용되어 클라이언트에 노출되지 않습니다. raw provider URL 직접 호출 금지 (안티 패턴).
      */
     chat(request: AIChatRequest): Promise<AIChatResponse>;
     /**

package/dist/index.d.ts

@@ -7519,11 +7519,37 @@ interface AIStreamChunk {
  * })
  * ```
  */
+/**
+ * # 🔒 보안 — LLM API key 는 절대 클라이언트에 hardcode 금지
+ *
+ * 본 SDK 의 `chat` / `chatStream` 은 **ConnectBase 서버 프록시 경유** — provider (OpenAI/Claude/
+ * Gemini/Ollama/vLLM/...) API key 는 `AppAIConfig` 에 암호화 저장된 상태로 ConnectBase 가 server-side
+ * 에서만 복호화하여 사용합니다. 클라이언트는 user public key (또는 secret key) 만 알면 됩니다.
+ *
+ * **❌ 안티 패턴 — 즉시 다른 운영자에게 cross_app_issue 로 알려지고 차단됨**:
+ * ```ts
+ * // 브라우저 정적 자산에 raw provider URL + key — 절대 금지
+ * fetch("https://api.openai.com/v1/chat/completions", {
+ *     headers: { Authorization: "Bearer sk-..." }
+ * })
+ * // 또는
+ * fetch("https://tunnel.connectbase.world/<id>/v1/chat/completions", {
+ *     headers: { Authorization: "Bearer <vLLM key>" }
+ * })
+ * ```
+ * DevTools → Network 한 번이면 누구나 key 추출 → 추론 비용 폭주 / GPU 자원 고갈.
+ *
+ * **✅ 베스트프랙티스 — 본 SDK 호출만 사용**:
+ * ```ts
+ * await cb.ai.chatStream({ messages: [...], provider: "openai_compatible" }, callbacks)
+ * ```
+ */
 declare class AIAPI {
     private http;
     constructor(http: HttpClient);
     /**
-     * AI 채팅 (동기)
+     * AI 채팅 (동기). ConnectBase 서버 프록시 경유 — provider API key 는 server-side `AppAIConfig`
+     * 에서만 사용되어 클라이언트에 노출되지 않습니다. raw provider URL 직접 호출 금지 (안티 패턴).
      */
     chat(request: AIChatRequest): Promise<AIChatResponse>;
     /**

package/dist/index.js

@@ -8487,7 +8487,8 @@ var AIAPI = class {
     this.http = http;
   }
   /**
-   * AI 채팅 (동기)
+   * AI 채팅 (동기). ConnectBase 서버 프록시 경유 — provider API key 는 server-side `AppAIConfig`
+   * 에서만 사용되어 클라이언트에 노출되지 않습니다. raw provider URL 직접 호출 금지 (안티 패턴).
    */
   async chat(request) {
     return this.http.post("/v1/public/ai/chat", request);

package/dist/index.mjs

@@ -8442,7 +8442,8 @@ var AIAPI = class {
     this.http = http;
   }
   /**
-   * AI 채팅 (동기)
+   * AI 채팅 (동기). ConnectBase 서버 프록시 경유 — provider API key 는 server-side `AppAIConfig`
+   * 에서만 사용되어 클라이언트에 노출되지 않습니다. raw provider URL 직접 호출 금지 (안티 패턴).
    */
   async chat(request) {
     return this.http.post("/v1/public/ai/chat", request);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "connectbase-client",
-  "version": "3.25.1",
+  "version": "3.26.0",
   "description": "Connect Base JavaScript/TypeScript SDK for browser and Node.js",
   "repository": {
     "type": "git",