connectbase-client 1.4.1 → 1.5.0

package/CHANGELOG.md

@@ -3,6 +3,39 @@
 본 SDK 의 모든 주요 변경사항을 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 형식으로 기록합니다.
 버전은 [Semantic Versioning](https://semver.org/lang/ko/) 을 따릅니다.
 
+## [1.5.0] - 2026-04-19
+
+터널의 proxy_token UX 정리 — 콘솔 AI Config 경로(95%+ 사용자)는 토큰을 건드리지 않고, curl/웹훅처럼 외부에서 터널 URL 을 직접 호출하는 소수 케이스에만 명시적 플래그로 opt-in 하도록 분리.
+
+### Added
+
+- **`--public` 플래그**: proxy_token 검증을 비활성화한 채 터널을 연다. Stripe/GitHub 등 커스텀 헤더를 못 붙이는 웹훅 수신용. tunnel-server 가 `?public=1` 쿼리를 받아 `Tunnel.Public=true` 로 등록하고 proxy_handler 가 토큰 검증을 skip. 활성화 시 CLI 는 눈에 띄는 노란 경고를 출력 (`cli.ts` handleMessage, `backend/cmd/tunnel-server/app/handler/proxy_handler.go`).
+- **`--show-token` 플래그**: proxy_token 값과 `curl -H "X-Proxy-Token: ..."` / `?proxy_token=` 예시를 CLI 에 출력. curl 로 터널을 직접 때려보고 싶을 때만 사용.
+- **감사 로그·메트릭**: 공개 모드 터널 세션 생성 시 `tunnel_public_opened_total{app_id}` 카운터 증가 + 매 요청마다 remote IP/method/path 가 `Public tunnel access` 로그로 남음.
+
+### Changed
+
+- **터널 기동 시 proxy_token 기본 숨김**: 1.4.1 에서 추가했던 "토큰 + curl 예시 자동 출력"을 제거. 기본 터널 사용자는 콘솔 AI Config 가 서버에서 자동으로 토큰을 resolve 하므로 CLI 에 노출할 필요가 없다. 필요하면 `--show-token` 으로 명시적으로 꺼냄.
+- **`tunnel_ready` 프로토콜 메시지에 `public` 필드 추가**: 서버가 CLI 에 현재 세션의 공개 여부를 내려주어 CLI 가 올바른 안내를 출력하도록 함 (`protocol/message.go`).
+
+### Why
+
+(1) 1.4.1 의 토큰 자동 출력은 기본 플로우(콘솔 AI Config)에서는 "내가 뭘 해야 하나?" 혼란을 유발했다. 대부분 사용자는 토큰 존재조차 모르는 게 맞다. (2) Stripe/GitHub 처럼 커스텀 헤더를 못 실어 보내는 웹훅 수신처는 `?proxy_token=` 쿼리 번거로움 + 세션 재시작 시 재등록 문제가 있었다. `--public` 으로 opt-in 할 수 있게 해 이 케이스를 깔끔히 분리.
+
+## [1.4.2] - 2026-04-18
+
+`npx connectbase docs` 명령이 init/deploy/tunnel 과 달리 brower auth 흐름을 거치지 않아, Public Key 가 없는 사용자가 키 발급 경로를 모른 채 prompt 만 보던 UX 문제 해결.
+
+### Fixed
+
+- **`docs` 가 키 없을 때 자동 발급 흐름을 트리거**: `.connectbaserc.publicKey` → `secretKey` 가 있으면 앱 선택만, 없으면 `browserAuthFlow()` → 앱 선택/생성 → Public Key 신규 발급 → `.connectbaserc` 저장까지 자동 수행. 한 번 실행하면 다음부터는 추가 입력 없이 통과 (`cli.ts` `ensureDocsPublicKey`).
+- **`tunnelAppId` 캐시 공유**: docs 와 tunnel 이 동일한 `.connectbaserc.tunnelAppId` 를 사용하므로 한쪽에서 앱을 선택하면 다른 쪽에서도 재사용된다.
+- **죽은 fallback 정리**: `config.publicKey ?? config.publicKey` (자기 자신 fallback), `!config.publicKey && !config.publicKey` (동일 변수 두 번 검사) 제거.
+
+### Internal
+
+- `resolveAppForTunnel` → `resolveApp` 으로 일반화. 새 앱 생성 시 백엔드(`POST /v1/public/cli/apps`) 응답에 포함된 `public_key` 를 같이 반환하도록 시그니처 확장. tunnel 호출부는 동작 동일.
+
 ## [1.4.1] - 2026-04-18
 
 `connectbase tunnel` CLI 가 공개 URL 호출에 필요한 **proxy token** 을 표시하지 않아, 사용자가 토큰을 알 방법이 없어 모든 요청이 `401 invalid or missing proxy token` 으로 막히던 문제 해결.

package/dist/cli.js

@@ -845,6 +845,70 @@ function detectMonorepo(gitRoot) {
   }
   return result;
 }
+async function ensureDocsPublicKey(config) {
+  if (config.publicKey) return config.publicKey;
+  const rcPath = path2.join(process.cwd(), ".connectbaserc");
+  const baseUrl = config.baseUrl || DEFAULT_BASE_URL;
+  const readRc = () => {
+    if (!fs2.existsSync(rcPath)) return {};
+    try {
+      return JSON.parse(fs2.readFileSync(rcPath, "utf-8"));
+    } catch {
+      return {};
+    }
+  };
+  const writeRc = (data) => {
+    fs2.writeFileSync(rcPath, JSON.stringify(data, null, 2) + "\n");
+    addToGitignore(".connectbaserc");
+  };
+  let secretKey = config.secretKey;
+  if (!secretKey) {
+    info("Public Key \uBC1C\uAE09\uC744 \uC704\uD574 \uBE0C\uB77C\uC6B0\uC800 \uC778\uC99D\uC744 \uC2DC\uC791\uD569\uB2C8\uB2E4...");
+    secretKey = await browserAuthFlow();
+    const rc2 = readRc();
+    rc2.secretKey = secretKey;
+    writeRc(rc2);
+    config.secretKey = secretKey;
+  }
+  const savedAppId = readRc().tunnelAppId || "";
+  const resolved = await resolveApp(secretKey, baseUrl, savedAppId);
+  let publicKey = resolved.publicKey;
+  if (!publicKey) {
+    info("Public Key \uBC1C\uAE09 \uC911...");
+    const res = await makeRequest(
+      `${baseUrl}/v1/public/cli/apps/${resolved.appId}/public-keys`,
+      "POST",
+      { "X-Public-Key": secretKey },
+      JSON.stringify({ name: "CLI Docs Key" })
+    );
+    if (res.status !== 201) {
+      const data2 = res.data;
+      const detail = data2?.error || data2?.message || `HTTP ${res.status}`;
+      error(`Public Key \uBC1C\uAE09 \uC2E4\uD328: ${detail}`);
+      process.exit(1);
+    }
+    const data = res.data;
+    if (!data.key) {
+      error("Public Key \uBC1C\uAE09 \uC751\uB2F5\uC774 \uBE44\uC5B4 \uC788\uC2B5\uB2C8\uB2E4");
+      process.exit(1);
+    }
+    publicKey = data.key;
+    success("Public Key \uBC1C\uAE09 \uC644\uB8CC");
+  }
+  const rc = readRc();
+  let changed = false;
+  if (rc.publicKey !== publicKey) {
+    rc.publicKey = publicKey;
+    changed = true;
+  }
+  if (rc.tunnelAppId !== resolved.appId) {
+    rc.tunnelAppId = resolved.appId;
+    changed = true;
+  }
+  if (changed) writeRc(rc);
+  config.publicKey = publicKey;
+  return publicKey;
+}
 async function downloadDocs(publicKey, templates, baseDir) {
   if (!baseDir) {
     baseDir = getProjectRoot();
@@ -1391,9 +1455,9 @@ function getTunnelServerUrl(baseUrl) {
   }
   return baseUrl.replace(/:\d+/, ":8090");
 }
-async function resolveAppForTunnel(secretKey, baseUrl, appIdOption) {
+async function resolveApp(secretKey, baseUrl, appIdOption) {
   if (appIdOption) {
-    return appIdOption;
+    return { appId: appIdOption };
   }
   let apps = [];
   try {
@@ -1418,7 +1482,7 @@ async function resolveAppForTunnel(secretKey, baseUrl, appIdOption) {
   }
   if (apps.length === 1) {
     success(`\uC571 \uC790\uB3D9 \uC120\uD0DD: ${apps[0].name}`);
-    return apps[0].id;
+    return { appId: apps[0].id };
   }
   if (apps.length > 0) {
     log(`
@@ -1434,7 +1498,7 @@ ${colors.blue}?${colors.reset} \uC571 \uC120\uD0DD (\uBC88\uD638): `);
   const num = parseInt(choice, 10);
   if (num > 0 && num <= apps.length) {
     success(`\uC120\uD0DD\uB428: ${apps[num - 1].name}`);
-    return apps[num - 1].id;
+    return { appId: apps[num - 1].id };
   }
   const projectName = path2.basename(process.cwd());
   const appName = await prompt(`${colors.blue}?${colors.reset} \uC571 \uC774\uB984 (${projectName}): `) || projectName;
@@ -1456,7 +1520,7 @@ ${colors.blue}?${colors.reset} \uC571 \uC120\uD0DD (\uBC88\uD638): `);
   }
   const createData = createRes.data;
   success(`\uC571 \uC0DD\uC131 \uC644\uB8CC: ${createData.app_name}`);
-  return createData.app_id;
+  return { appId: createData.app_id, publicKey: createData.public_key };
 }
 function acquireTunnelLock2(appID, port, force) {
   const result = acquireTunnelLock(appID, port, force, VERSION);
@@ -1505,7 +1569,7 @@ async function startTunnel(port, config, tunnelOpts) {
     } catch {
     }
   }
-  const appId = await resolveAppForTunnel(tunnelKey, config.baseUrl, savedAppId);
+  const { appId } = await resolveApp(tunnelKey, config.baseUrl, savedAppId);
   try {
     let rcData = {};
     if (fs2.existsSync(rcPath)) {
@@ -1531,6 +1595,9 @@ async function startTunnel(port, config, tunnelOpts) {
   if (tunnelOpts?.maxBody) {
     wsPath += `&max_body=${tunnelOpts.maxBody}`;
   }
+  if (tunnelOpts?.public) {
+    wsPath += `&public=1`;
+  }
   let reconnectAttempts = 0;
   const maxReconnectAttempts = 10;
   let shouldReconnect = true;
@@ -1664,18 +1731,25 @@ ${colors.cyan}ConnectBase Tunnel${colors.reset}`);
       case "tunnel_ready": {
         const proxyToken = typeof msg.proxy_token === "string" ? msg.proxy_token : "";
         const tunnelUrl = typeof msg.url === "string" ? msg.url : "";
+        const isPublic = msg.public === true;
         success(`\uD130\uB110 \uD65C\uC131\uD654!`);
         log(`${colors.green}\u2192${colors.reset} URL:   ${colors.cyan}${tunnelUrl}${colors.reset}`);
         log(`${colors.green}\u2192${colors.reset} \uB85C\uCEEC:  ${colors.cyan}http://localhost:${localPort}${colors.reset}`);
-        if (proxyToken) {
-          log(`${colors.green}\u2192${colors.reset} \uD1A0\uD070:  ${colors.yellow}${proxyToken}${colors.reset}`);
-        }
         if (msg.timeout || msg.max_body) {
           log(`${colors.green}\u2192${colors.reset} \uC124\uC815:  timeout=${colors.cyan}${msg.timeout}s${colors.reset}, max-body=${colors.cyan}${msg.max_body}MB${colors.reset}`);
         }
-        if (proxyToken && tunnelUrl) {
+        if (isPublic) {
+          log("");
+          log(`${colors.yellow}\u26A0  \uACF5\uAC1C \uBAA8\uB4DC (--public):${colors.reset} proxy_token \uAC80\uC99D\uC774 \uBE44\uD65C\uC131\uD654\uB410\uC2B5\uB2C8\uB2E4.`);
+          log(`   ${colors.dim}tunnelID \uB97C \uC544\uB294 \uB204\uAD6C\uB098 \uC774 URL \uB85C \uB85C\uCEEC \uC11C\uBE44\uC2A4\uC5D0 \uC811\uADFC\uD560 \uC218 \uC788\uC2B5\uB2C8\uB2E4.${colors.reset}`);
+          log(`   ${colors.dim}\uC6F9\uD6C5 \uC218\uC2E0 / \uC678\uBD80 \uC11C\uBE44\uC2A4 \uC5F0\uB3D9 \uBAA9\uC801\uC5D0 \uD55C\uD574 \uC0AC\uC6A9\uD558\uACE0, \uBBFC\uAC10 \uB370\uC774\uD130\uB294 \uCDE8\uAE09\uD558\uC9C0 \uB9C8\uC138\uC694.${colors.reset}`);
+          log("");
+          log(`${colors.dim}  $ curl ${tunnelUrl}/${colors.reset}`);
+        } else if (tunnelOpts?.showToken && proxyToken && tunnelUrl) {
+          log("");
+          log(`${colors.green}\u2192${colors.reset} \uD1A0\uD070:  ${colors.yellow}${proxyToken}${colors.reset}`);
           log(`
-${colors.dim}\uACF5\uAC1C URL \uD638\uCD9C \uC2DC \uB2E4\uC74C \uD5E4\uB354 \uB610\uB294 \uCFFC\uB9AC\uB85C \uD1A0\uD070\uC744 \uC804\uB2EC\uD558\uC138\uC694:${colors.reset}`);
+${colors.dim}\uC678\uBD80 \uC9C1\uC811 \uD638\uCD9C \uC2DC \uB2E4\uC74C \uD5E4\uB354 \uB610\uB294 \uCFFC\uB9AC\uB85C \uD1A0\uD070\uC744 \uC804\uB2EC\uD558\uC138\uC694:${colors.reset}`);
           log(`${colors.dim}  $ curl -H "X-Proxy-Token: ${proxyToken}" ${tunnelUrl}/${colors.reset}`);
           log(`${colors.dim}  $ curl "${tunnelUrl}/?proxy_token=${proxyToken}"${colors.reset}`);
         }
@@ -1849,6 +1923,8 @@ ${colors.yellow}\uC635\uC158:${colors.reset}
   -t, --timeout <sec>   \uD130\uB110 \uC694\uCCAD \uD0C0\uC784\uC544\uC6C3 (\uCD08, tunnel \uC804\uC6A9)
   --max-body <MB>       \uD130\uB110 \uCD5C\uB300 \uBC14\uB514 \uD06C\uAE30 (MB, tunnel \uC804\uC6A9)
   --force               \uD130\uB110 lockfile \uBB34\uC2DC (\uC911\uBCF5 \uC2E4\uD589 \uAC15\uC81C, tunnel \uC804\uC6A9)
+  --public              proxy_token \uAC80\uC99D \uBE44\uD65C\uC131\uD654 \u2014 \uC6F9\uD6C5/\uC678\uBD80 \uC9C1\uC811 \uD638\uCD9C\uC6A9 (tunnel \uC804\uC6A9)
+  --show-token          proxy_token \uACFC curl \uC608\uC2DC\uB97C \uCD9C\uB825 (--public \uC544\uB2CC \uACBD\uC6B0)
   -d, --dev             Dev \uD658\uACBD\uC5D0 \uBC30\uD3EC (deploy \uC804\uC6A9)
   --check               \uBC84\uC804\uB9CC \uD655\uC778 (update \uC804\uC6A9)
   --skip-docs           \uBB38\uC11C \uC5C5\uB370\uC774\uD2B8 \uAC74\uB108\uB6F0\uAE30 (update \uC804\uC6A9)
@@ -1926,6 +2002,10 @@ function parseArgs(args) {
       result.options.appId = args[++i];
     } else if (arg === "--force") {
       result.options.force = "true";
+    } else if (arg === "--public") {
+      result.options.public = "true";
+    } else if (arg === "--show-token") {
+      result.options.showToken = "true";
     } else if (arg === "-d" || arg === "--dev") {
       result.options.dev = "true";
     } else if (arg === "--check") {
@@ -1978,20 +2058,13 @@ async function main() {
       setupRoot: parsed.options.setupRoot === "true"
     });
   } else if (parsed.command === "docs") {
-    let docsPublicKey = config.publicKey ?? config.publicKey;
-    if (!docsPublicKey) {
-      docsPublicKey = await prompt(`${colors.blue}?${colors.reset} Public Key: `);
-      if (!docsPublicKey) {
-        error("Public Key\uB294 \uD544\uC218\uC785\uB2C8\uB2E4");
-        process.exit(1);
-      }
-    }
+    const docsPublicKey = await ensureDocsPublicKey(config);
     await downloadDocs(docsPublicKey);
   } else if (parsed.command === "mcp") {
     await setupMcp();
   } else if (parsed.command === "deploy") {
     const directory = parsed.args[0] || fileConfig.deployDir || ".";
-    if (!config.publicKey && !config.publicKey) {
+    if (!config.publicKey) {
       error('Public Key\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4. "npx connectbase init"\uC73C\uB85C \uC124\uC815\uD558\uAC70\uB098 -k \uC635\uC158\uC744 \uC0AC\uC6A9\uD558\uC138\uC694');
       process.exit(1);
     }
@@ -2027,6 +2100,12 @@ async function main() {
     if (parsed.options.force === "true") {
       tunnelOpts.force = true;
     }
+    if (parsed.options.public === "true") {
+      tunnelOpts.public = true;
+    }
+    if (parsed.options.showToken === "true") {
+      tunnelOpts.showToken = true;
+    }
     await startTunnel(port, config, tunnelOpts);
   } else {
     error(`\uC54C \uC218 \uC5C6\uB294 \uBA85\uB839\uC5B4: ${parsed.command}`);

package/package.json

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