connectbase-client 6.0.0 → 6.2.0

package/CHANGELOG.md

@@ -3,6 +3,172 @@
 본 SDK 의 모든 주요 변경사항을 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 형식으로 기록합니다.
 버전은 [Semantic Versioning](https://semver.org/lang/ko/) 을 따릅니다.
 
+## [6.2.0] - 2026-09-06
+
+### Added — 웹 스토리지 관리 API 에 Secret Key 전송
+
+`deploy`, `promote`, `releases` 와 `init` 의 스토리지 목록/생성이 이제 Secret Key(`cb_sk_*`)를
+함께 보냅니다. `.connectbaserc` 의 `secretKey` 또는 `CONNECTBASE_SECRET_KEY` 환경변수에서
+자동으로 읽습니다. **`init` 을 이미 실행했다면 할 일이 없습니다.**
+
+**왜 필요한가.** Public Key(`cb_pk_*`)는 비밀이 아닙니다. 브라우저 번들에 실려 배포되는 공개
+식별자이고, 실제로 운영 중인 사이트의 JS 에서 그대로 추출됩니다. 그런데 이 값 하나로 배포와
+production 승격이 가능했습니다 — 공개된 사이트에서 키를 뽑은 제3자가 그 사이트를 통째로
+교체할 수 있었다는 뜻입니다. Public Key 는 "어느 앱인가" 를 말할 뿐 "이 앱을 다룰 자격이
+있는가" 를 증명하지 못하므로, 쓰기 동작의 자격증명이 될 수 없습니다.
+
+**서버는 곧 이를 요구합니다.** 현재는 기존 배포 파이프라인이 끊기지 않도록 유예 중이고,
+이 버전이 충분히 퍼진 뒤 강제로 전환합니다. 그때부터 Secret Key 없는 호출은 401
+`SECRET_KEY_REQUIRED` 로 거부됩니다.
+
+**이 버전은 아무것도 깨뜨리지 않습니다.** Secret Key 가 없으면 경고만 하고 그대로 진행합니다.
+CLI 가 서버보다 먼저 조이면, 우리가 생성해 드리는 GitHub Actions 워크플로처럼 버전을 고정하지
+않는(`npx --yes connectbase deploy`) 환경이 서버 변경 전에 깨지기 때문입니다.
+
+**지금 해두실 것.** CI 를 쓰신다면 저장소 시크릿에 `CONNECTBASE_SECRET_KEY` 를 추가하고
+워크플로 env 에 넣으세요. 워크플로 파일에 값을 직접 적으면 저장소에 커밋됩니다.
+
+```yaml
+env:
+  CONNECTBASE_PUBLIC_KEY: ${{ secrets.CONNECTBASE_PUBLIC_KEY }}
+  CONNECTBASE_SECRET_KEY: ${{ secrets.CONNECTBASE_SECRET_KEY }}
+```
+
+`page-metas` 계열 API 는 **변경 없습니다** — 브라우저 SDK 의 정규 경로라 그대로 둡니다.
+
+### Added — `X-User-Secret-Key` 전용 헤더
+
+Secret Key 를 `Authorization` 대신 전용 헤더로도 보냅니다.
+
+`Authorization` 자리는 AppMember 세션 토큰이 먼저 차지합니다. 종전 SDK 는 그 헤더가 이미
+있으면 Secret Key 를 붙이지 않았기 때문에, **로그인 상태 브라우저에서는 `secretKey` 를 설정해도
+전송되지 않았습니다.** 두 자격증명은 역할이 다릅니다 — 멤버 토큰은 "누가 이 앱의 회원인가",
+Secret Key 는 "이 호출자가 앱을 관리할 자격이 있는가". 한 헤더를 두고 다투게 두면 관리 동작이
+로그인 상태에서만 조용히 실패합니다.
+
+서버는 전용 헤더를 `Authorization` 보다 우선해 읽습니다. 기존 `Authorization` 경로도 그대로
+보내므로 구버전 서버와 호환됩니다.
+
+> Secret Key 는 서버사이드 자격증명입니다. 브라우저 번들에 넣지 마세요.
+
+### Fixed — 대용량 파일 배포 시 원인 불명 500
+
+파일당 저장 한도(약 6 MiB, 바이너리는 base64 로 약 1.33배)를 넘으면 서버가 원시 DB 오류를
+500 으로 뭉개 반환했습니다. 이제 **413** 과 함께 초과 파일 목록, 원본 크기 추정치, presign
+경로 안내가 응답에 담깁니다. CLI 는 종전대로 대용량 바이너리를 자동으로 오프로드합니다.
+
+## [6.1.0] - 2026-09-01
+
+### Added — `cb.organizations.*`: 조직/팀(워크스페이스)
+
+앱의 **엔드유저가 만드는 조직**을 다루는 모듈입니다. Connect Base 콘솔의 협업자 RBAC
+(`cb.roles.*`)와는 완전히 별개 시스템입니다.
+
+| 메서드 | 설명 |
+|---|---|
+| `create` / `listMine` / `get` / `update` / `delete` | 조직 CRUD (`slug` 는 생성 후 변경 불가) |
+| `listMembers` / `updateMemberRole` / `removeMember` | 멤버 관리 (본인 ID 로 `removeMember` 하면 탈퇴) |
+| `createInvitation` / `listInvitations` / `revokeInvitation` / `acceptInvitation` | 초대 |
+| `switchTo` | 조직 전환 — 조직 컨텍스트가 실린 새 액세스 토큰을 받아 SDK 에 자동 적용 |
+
+모든 조직 API 는 **로그인한 회원 토큰**을 요구합니다. 퍼블릭 키만으로 호출하면 401 입니다 —
+퍼블릭 키는 설계상 클라이언트 번들에 노출되는 값이라, 그것만으로 목록을 열면 앱의 조직 구조가
+통째로 덤프되기 때문입니다.
+
+> #### 조직 컨텍스트는 10분마다 갱신해야 합니다
+>
+> `switchTo()` 가 심는 RLS 조직 컨텍스트(`auth.org_id` / `auth.org_role`)의 수명은 액세스
+> 토큰(1시간)과 **독립적인 10분**입니다. 만료되어도 토큰 자체는 유효해 401 이 나지 않고,
+> 조직 규칙만 fail-closed 로 거부되어 **"멀쩡하던 조회가 갑자기 전부 막히는"** 증상으로만
+> 드러납니다. 반환값의 `org_context_expires_in`(초) 보다 먼저 다시 호출하세요.
+> 토큰 회전(refresh)이 일어나도 조직 컨텍스트는 의도적으로 사라지므로 다시 호출해야 합니다.
+
+```typescript
+let timer: ReturnType<typeof setTimeout> | undefined
+
+async function activate(orgId: string) {
+    const ctx = await cb.organizations.switchTo(orgId)
+    clearTimeout(timer)
+    timer = setTimeout(
+        () => activate(orgId),
+        Math.max(ctx.org_context_expires_in - 60, 30) * 1000,
+    )
+    return ctx
+}
+```
+
+### Changed — `subscription.deleteBillingKey()` 가 삭제 결과를 반환합니다
+
+반환 타입이 `Promise<void>` 에서 `Promise<DeleteBillingKeyResponse>` 로 바뀌었습니다.
+서버는 이전부터 이 본문을 보내고 있었지만 타입에 노출되지 않아, **"PG 등록이 남아 있다"는
+경고를 SDK 사용자가 볼 수 없었습니다.**
+
+```typescript
+const result = await cb.subscription.deleteBillingKey(billingKeyId)
+if (!result.provider_revoked) {
+    // Connect Base 기록만 지워졌고 PG 등록은 그대로 남아 있다
+    alert(result.provider_revoke_note)
+}
+```
+
+| 프로바이더 | PG 해지 | 동작 |
+|---|---|---|
+| `toss` | O | 토스 빌링키 삭제 API 호출. PG 삭제가 실패하면 DB 행도 지우지 않고 에러 |
+| `payapp` / `paypal` / `paddle` / `stripe` | X | "결제수단 삭제" API 가 없어 기록만 삭제. `provider_revoked: false` + `provider_revoke_note` |
+
+반환값을 쓰지 않던 기존 호출은 그대로 동작합니다 (하위호환).
+
+### Added — `DeleteBillingKeyResponse` 타입
+
+`message` / `provider` / `provider_revoked` / `provider_revoke_note?`.
+
+### Added — 퍼블릭 키 스코프와 무중단 회전
+
+- `cb.publicKey.createPublicKey()` 가 `scopes` 를 받습니다. **비우면 전권**이고(기존 키가 전부
+  그렇습니다), 어휘는 새로 만든 것이 아니라 콘솔 RBAC 권한 이름과 service_role
+  `management_scopes` 의 합집합입니다.
+- `PublicKeyItem` / `CreatePublicKeyResponse` / `UpdatePublicKeyResponse` 에 `scopes` 가 실립니다.
+  `PublicKeyItem` 에는 발급 출처 감사 필드(`created_by_kind`, `created_by_user_id`,
+  `created_ip_masked`, `created_user_agent`)도 추가됐습니다.
+- **`cb.publicKey.rotatePublicKey(appId, keyId, { grace_period_hours?, name? })`** 신설 —
+  새 키를 발급하고 옛 키는 유예 기간(기본 24시간, `0` = 즉시, 상한 720시간) 뒤 만료됩니다.
+  옛 키의 스코프와 `payment_mode` 는 새 키가 물려받습니다. 반환값의 `new_key.key` 는 이때만
+  볼 수 있고, `previous_key_expires_at` 전에 클라이언트 배포를 끝내야 합니다.
+
+```typescript
+const rotated = await cb.publicKey.rotatePublicKey('app-id', 'key-id', { grace_period_hours: 72 })
+console.log(rotated.new_key.key, rotated.previous_key_expires_at)
+```
+
+### Added — `HttpClient.setAccessToken()`
+
+refresh token 을 건드리지 않고 액세스 토큰만 교체합니다. 조직 컨텍스트 발급처럼 **새 액세스
+토큰만 돌려주는** 엔드포인트를 위한 것으로, `cb.organizations.switchTo()` 가 내부에서 씁니다.
+
+---
+
+## [6.0.1] - 2026-08-22
+
+### Fixed — 로그인 세션이 없을 때 `/v1/auth/re-issue` 401 이 반복해서 나가던 문제
+
+쿠키 세션이 없는 브라우저(제3자 쿠키 차단, 쿠키 삭제, 만료 등)에서 인증이 필요한 API 를
+호출하면 SDK 가 매번 "쿠키로 세션을 복구해 보자"며 `/v1/auth/re-issue` 를 한 번씩 더
+보냈고, 그 요청이 401 로 떨어졌습니다. 앱이 폴링을 하거나 화면/훅마다 클라이언트를 새로
+만드는 구조면 이 401 이 수 초 간격으로 계속 쌓입니다 (실측: 5~6초 간격으로 13분 이상 연속,
+platform-issue `01a0237f`).
+
+동시 refresh 를 하나로 합치는 처리(single-flight)는 이전부터 있었지만 **클라이언트 인스턴스
+하나가 살아 있는 동안만** 유효해서, 인스턴스가 새로 만들어지면 백오프까지 함께 초기화되는
+것이 원인이었습니다.
+
+이제 쿠키만으로 시도한 재발급이 401/403 을 받으면 "지금 이 브라우저에는 쓸 수 있는 refresh
+쿠키가 없다"를 60초 동안 `localStorage` 에 기록하고, 그동안은 **인스턴스가 달라도** 재발급
+요청을 보내지 않습니다. 로그인(`setTokens`)이나 성공한 재발급은 이 기록을 즉시 지우므로
+세션이 생기는 즉시 정상 동작합니다. 메모리에 refresh token 을 들고 있는 호출은 자격이
+다르므로 영향받지 않습니다.
+
+동작 변화는 "불필요한 401 요청이 사라지는 것"뿐입니다 — 세션 복구 성공 조건은 그대로입니다.
+
 ## [6.0.0] - 2026-08-20
 
 ### BREAKING — `realtime.isConnected()` 가 SSE 폴백에서 더 이상 true 를 반환하지 않습니다

package/README.md

@@ -27,13 +27,19 @@ Connect Base provides **two types** of Keys. Use the right key for your use case
 |---------|----------|---------|
 | Frontend SDK (`new ConnectBase()`) | **Public Key** (`cb_pk_`) | Web/app: DB queries, auth, file uploads |
 | `.env` file (`VITE_CONNECTBASE_PUBLIC_KEY`) | **Public Key** (`cb_pk_`) | React, Vue, etc. |
-| CLI deploy (`.connectbaserc`) | **Public Key** (`cb_pk_`) | `npx connectbase deploy` |
+| CLI deploy (`.connectbaserc`) | **Public Key + Secret Key** (`cb_pk_` + `cb_sk_`) | `npx connectbase deploy` |
 | MCP server (AI tools) | **Secret Key** (`cb_sk_`) | Claude, Cursor, Windsurf |
 | Server-side admin tasks | **Secret Key** (`cb_sk_`) | Backend full data access |
 
 > ⚠️ **MCP server rejects Public Keys** — you must use a Secret Key (`cb_sk_`).
 >
 > ⚠️ **Never use Secret Keys in frontend code** — RLS is bypassed, exposing all data.
+>
+> 🔐 **Web storage deploys need both keys.** A Public Key ships inside your browser bundle, so
+> anyone can read it out of a deployed site's JS — it cannot prove you may replace that site.
+> The web storage list/create/deploy/promote routes therefore require
+> `Authorization: Bearer cb_sk_*` **in addition to** `X-Public-Key`; without it they return
+> **401 `SECRET_KEY_REQUIRED`**. The CLI sends it for you — see [CLI](#cli).
 
 Create Keys in the Console under **Settings > API tab**. Choose Public or Secret type when creating. The full key is shown **only once** at creation time.
 
@@ -113,6 +119,7 @@ try {
 - **Push Notifications**: Cross-platform push notification support
 - **WebRTC**: Real-time audio/video communication
 - **Payments**: Subscription and one-time payment support
+- **Organizations**: End-user workspaces/teams with invitations and an RLS organization context (`cb.organizations.*`)
 - **AI Streaming**: Real-time AI text generation via WebSocket (multi-provider: Gemini, OpenAI, Claude, Ollama, LM Studio, OpenAI-compatible)
 - **Knowledge Base (RAG)**: Document indexing + BM25 search with nori 한국어 형태소. PDF / DOCX / text file upload via `addDocumentFromFile`
 - **Endpoint**: Call your own GPU models on your own PC through one `cb_pk_*` key — ConnectBase forwards the payload as-is (dumb pipe)
@@ -124,6 +131,17 @@ try {
 
 Deploy your web application to Connect Base Web Storage with a single command.
 
+> 🔐 **Deploy commands require a Secret Key (`cb_sk_*`).** The web storage deploy, promote,
+> create and list routes require `Authorization: Bearer cb_sk_*` on top of `X-Public-Key`,
+> because a Public Key is a public identifier that ships in your browser bundle and cannot
+> prove deploy permission. The CLI reads `secretKey` from `.connectbaserc` or the
+> `CONNECTBASE_SECRET_KEY` environment variable and sends it automatically — **just update to
+> the latest version** (`npm i -g connectbase-client@latest`). Older CLIs fail with
+> **401 `SECRET_KEY_REQUIRED`**.
+>
+> **Never commit a Secret Key.** `init` adds `.connectbaserc` to `.gitignore`; in CI, inject it
+> from a repository secret instead.
+
 ### Quick Start
 
 ```bash
@@ -135,9 +153,10 @@ npm run deploy
 ```
 
 The `init` command will:
-- Ask for your Public Key
+- Ask for your Secret Key (`cb_sk_`) — or take it from `--secret-key` / `CONNECTBASE_SECRET_KEY`
+- Issue a Public Key for the app
 - List existing web storages or create a new one automatically
-- Create a `.connectbaserc` config file
+- Create a `.connectbaserc` config file (holds both keys)
 - Add `.connectbaserc` to `.gitignore`
 - Add a `deploy` script to `package.json` (includes `build` if available)
 
@@ -154,7 +173,14 @@ The `init` command will:
 If you prefer not to use `init`, you can pass options directly:
 
 ```bash
-npx connectbase deploy ./dist -s <storage-id> -k <public-key>
+npx connectbase deploy ./dist -s <storage-id> -k <public-key> --secret-key <secret-key>
+```
+
+The Secret Key can also come from `CONNECTBASE_SECRET_KEY` — preferred in CI, so it never
+appears in shell history or CI logs:
+
+```bash
+CONNECTBASE_SECRET_KEY=cb_sk_... npx connectbase deploy ./dist -s <storage-id> -k <public-key>
 ```
 
 ### Options
@@ -162,7 +188,8 @@ npx connectbase deploy ./dist -s <storage-id> -k <public-key>
 | Option | Alias | Description |
 |--------|-------|-------------|
 | `--storage <id>` | `-s` | Storage ID |
-| `--public-key <key>` | `-k` | API Key |
+| `--public-key <key>` | `-k` | Public Key (`cb_pk_`) — identifies the app |
+| `--secret-key <key>` | | Secret Key (`cb_sk_`) — required by `deploy` / `promote` / storage list & create. Prefer `CONNECTBASE_SECRET_KEY` in CI |
 | `--base-url <url>` | `-u` | Custom server URL |
 | `--timeout <sec>` | `-t` | Tunnel request timeout in seconds (tunnel only) |
 | `--max-body <MB>` | | Tunnel max body size in MB (tunnel only) |
@@ -228,20 +255,37 @@ The `init` command creates `.connectbaserc` automatically. You can also create i
 
 ```json
 {
-  "publicKey": "your-public-key",
+  "publicKey": "cb_pk_your-public-key",
+  "secretKey": "cb_sk_your-secret-key",
   "storageId": "your-storage-id",
   "deployDir": "./dist"
 }
 ```
 
+> ⚠️ `.connectbaserc` now holds a Secret Key — keep it in `.gitignore` (`init` adds it) and never
+> commit it. On a shared machine or in CI, drop `secretKey` from the file and pass
+> `CONNECTBASE_SECRET_KEY` instead.
+
 ### Environment Variables
 
 ```bash
-export CONNECTBASE_PUBLIC_KEY=your-public-key
+export CONNECTBASE_PUBLIC_KEY=cb_pk_your-public-key
+export CONNECTBASE_SECRET_KEY=cb_sk_your-secret-key   # required by deploy / promote
 export CONNECTBASE_STORAGE_ID=your-storage-id
 npx connectbase deploy ./dist
 ```
 
+In CI, read the Secret Key from a repository secret:
+
+```yaml
+# GitHub Actions
+- run: npx connectbase deploy ./dist
+  env:
+    CONNECTBASE_PUBLIC_KEY: ${{ vars.CONNECTBASE_PUBLIC_KEY }}
+    CONNECTBASE_SECRET_KEY: ${{ secrets.CONNECTBASE_SECRET_KEY }}
+    CONNECTBASE_STORAGE_ID: ${{ vars.CONNECTBASE_STORAGE_ID }}
+```
+
 ### Requirements
 
 - `index.html` must exist in the root of the deploy directory
@@ -1330,6 +1374,20 @@ call.disconnect()   // voice 는 그대로 유지됩니다
 
 ### Payments & Subscriptions
 
+> **빌링키 API 6종(발급/확인/목록/상세/수정/삭제)은 로그인한 회원 토큰이 필요합니다.**
+> `X-Public-Key` 단독 호출은 `401` 입니다. 로그인 없이 빌링키를 만들던 게스트 체크아웃 흐름은
+> 회원 로그인 후 호출로 바꿔야 합니다. 서버에서는 `cb_sk_*` 또는 `management_scopes` 에
+> `payment:read` / `subscription:manage` 를 opt-in 한 `service_role` 함수를 쓰세요.
+
+```typescript
+// 결제수단 삭제 — PG 등록까지 지워졌는지는 프로바이더마다 다르다 (v6.1.0+)
+const deleted = await cb.subscription.deleteBillingKey('billing-key-1')
+if (!deleted.provider_revoked) {
+  // toss 외 프로바이더: Connect Base 기록만 지워졌고 PG 등록은 남아 있다
+  console.warn(deleted.provider_revoke_note)
+}
+```
+
 ```typescript
 // Create a subscription (정기 결제)
 const subscription = await cb.subscription.create({
@@ -1384,6 +1442,60 @@ export async function handler(payload, ctx) {
 얹힙니다. payapp/paypal 은 PG 가 결제일 변경 API 를 주지 않아 400 `next_billing_date_unsupported`
 입니다 (로컬만 미루면 원래 날짜에 그대로 출금되므로 조용히 처리하지 않습니다).
 
+### Organizations (Teams / Workspaces)
+
+앱의 **엔드유저가 만드는 조직**. Connect Base 콘솔의 협업자 RBAC(`cb.roles.*`)와는 별개
+시스템이다. **모든 조직 API 는 로그인한 회원 토큰을 요구한다** — 퍼블릭 키 단독 호출은 401 이다.
+
+```typescript
+// 조직 만들기 (만든 사람이 owner)
+const org = await cb.organizations.create({ name: '우리 팀' })
+
+// 초대 — 평문 토큰은 이 응답에서만 볼 수 있고, 메일 발송은 앱이 직접 한다
+const { token } = await cb.organizations.createInvitation(org.id, {
+  email: 'teammate@example.com',
+  role: 'member',   // owner | admin | member
+})
+
+// 초대 수락 (초대받은 계정으로 로그인한 상태에서)
+await cb.organizations.acceptInvitation(token)
+
+// 내 조직 목록 (조직 전환 UI)
+const mine = await cb.organizations.listMine()
+```
+
+#### 조직 컨텍스트는 10분마다 갱신해야 한다
+
+데이터베이스 보안 규칙(RLS)의 `auth.org_id` / `auth.org_role` 은 **토큰에 실린 조직 컨텍스트**
+에서 온다. 이 컨텍스트의 수명은 액세스 토큰(1시간)과 **독립적인 10분**이다. 만료되어도 토큰
+자체는 유효해 401 이 나지 않고, 조직 규칙만 fail-closed 로 거부되어 **"멀쩡하던 조회가 갑자기
+전부 막히는"** 증상으로만 드러난다.
+
+```typescript
+let timer: ReturnType<typeof setTimeout> | undefined
+
+async function activate(orgId: string) {
+  // 새 액세스 토큰을 받아 SDK 에 자동 적용한다
+  const ctx = await cb.organizations.switchTo(orgId)
+  clearTimeout(timer)
+  // 만료 60초 전에 갱신
+  timer = setTimeout(() => activate(orgId), Math.max(ctx.org_context_expires_in - 60, 30) * 1000)
+  return ctx
+}
+```
+
+토큰 회전(refresh)이 일어나면 조직 컨텍스트는 의도적으로 사라지므로 `switchTo()` 를 다시
+호출해야 한다. 내가 속하지 않은 조직은 403 이 아니라 **404** 다 (조직 ID 열거 방지).
+
+RLS 규칙에서 쓸 수 있는 축:
+
+| 축 | 조직 컨텍스트가 없을 때 | 용도 |
+|---|---|---|
+| `auth.org_id` / `auth.org_role` | **에러 (fail-closed)** | `data.org_id == auth.org_id` 같은 스칼라 비교 |
+| `auth.has_org` | `false` (에러 안 남) | 조직 유무로 분기 |
+| `hasOrgRole('owner')` | `false` (에러 안 남) | 조직 역할 판정 (앱 전역 `hasRole()` 과 다름) |
+| `inOrg('<uuid>')` | `false` (에러 안 남) | 특정 조직인지, 인자 생략 시 컨텍스트 유무 |
+
 ### Support (End-user Issue Reporting)
 
 End-user 가 앱 운영자에게 직접 버그·질문·요청을 발행하는 채널. 운영자 콘솔의 inbox 에 들어가며, AI 가 자동으로 요약·긴급도·카테고리를 분류한다 (운영자가 AI config 등록 시).

package/dist/cli.js

@@ -41,7 +41,8 @@ __export(cli_exports, {
   normalizeRelativePath: () => normalizeRelativePath,
   parseArgs: () => parseArgs,
   registerEndpointBinding: () => registerEndpointBinding,
-  sha256Hex: () => sha256Hex
+  sha256Hex: () => sha256Hex,
+  storageAdminHeaders: () => storageAdminHeaders
 });
 module.exports = __toCommonJS(cli_exports);
 var crypto = __toESM(require("crypto"));
@@ -295,6 +296,41 @@ function normalizeRelativePath(relativePath) {
   if (!p.startsWith("/")) p = `/${p}`;
   return p;
 }
+function storageAdminHeaders(config) {
+  const headers = {
+    "X-Public-Key": config.publicKey
+  };
+  if (config.secretKey) {
+    headers["X-User-Secret-Key"] = config.secretKey;
+    headers.Authorization = `Bearer ${config.secretKey}`;
+    return headers;
+  }
+  warn("Secret Key(cb_sk_)\uAC00 \uC124\uC815\uB3FC \uC788\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4.");
+  log(
+    "  Public Key \uB294 \uBE0C\uB77C\uC6B0\uC800 \uBC88\uB4E4\uC5D0 \uACF5\uAC1C\uB418\uB294 \uAC12\uC774\uB77C \uBC30\uD3EC/\uC2B9\uACA9\uC758 \uC790\uACA9\uC99D\uBA85\uC774 \uB420 \uC218 \uC5C6\uC5B4,"
+  );
+  log("  \uACE7 \uC11C\uBC84\uAC00 Secret Key \uB97C \uC694\uAD6C\uD569\uB2C8\uB2E4. \uC9C0\uAE08 \uC124\uC815\uD574 \uB450\uC138\uC694.");
+  log(
+    `  ${colors.cyan}npx connectbase init${colors.reset} \uC774 \uBC1C\uAE09\uD574 .connectbaserc \uC5D0 \uC800\uC7A5\uD569\uB2C8\uB2E4.`
+  );
+  log(
+    `  \uC774\uBBF8 \uD0A4\uAC00 \uC788\uB2E4\uBA74 ${colors.cyan}CONNECTBASE_SECRET_KEY${colors.reset} \uD658\uACBD\uBCC0\uC218\uB85C \uC9C0\uC815\uD558\uC138\uC694.`
+  );
+  log("  CI \uC5D0\uC11C\uB294 \uC800\uC7A5\uC18C \uC2DC\uD06C\uB9BF\uC5D0 \uB123\uC73C\uC138\uC694 \u2014 \uC800\uC7A5\uC18C\uC5D0 \uCEE4\uBC0B\uD558\uBA74 \uC548 \uB429\uB2C8\uB2E4.");
+  return headers;
+}
+function reportDeployAuthError(status, data) {
+  if (status !== 401) return false;
+  const detail = data?.error;
+  if (detail?.code !== "SECRET_KEY_REQUIRED") return false;
+  error(detail.message || "\uC774 \uC694\uCCAD\uC5D0\uB294 Secret Key \uAC00 \uD544\uC694\uD569\uB2C8\uB2E4.");
+  if (detail.suggestion) {
+    log("");
+    log(`  ${detail.suggestion}`);
+  }
+  log("");
+  return true;
+}
 function loadConfig() {
   const config = {
     publicKey: process.env.CONNECTBASE_PUBLIC_KEY,
@@ -670,7 +706,7 @@ async function deploy(directory, config, isDev = false, deployOpts = {}) {
     );
   }
   const baseStorageUrl = `${config.baseUrl}/v1/public/storages/webs/${config.storageId}`;
-  const headers = { "X-Public-Key": config.publicKey };
+  const headers = storageAdminHeaders(config);
   const timeoutMs = computeDeployTimeout(totalSize, deployOpts.timeoutMs);
   log(
     `${colors.dim}\uD0C0\uC784\uC544\uC6C3: ${Math.round(timeoutMs / 1e3)}\uCD08${colors.reset}`
@@ -897,13 +933,15 @@ ${colors.cyan}URL: ${data.url}${colors.reset}
   } else {
     const data = response.data;
     const errorMsg = typeof data === "object" && data !== null ? data.message || data.error || JSON.stringify(data) : typeof data === "string" ? data : `HTTP ${response.status}`;
-    error(`\uBC30\uD3EC \uC2E4\uD328: ${errorMsg}`);
+    if (!reportDeployAuthError(response.status, response.data)) {
+      error(`\uBC30\uD3EC \uC2E4\uD328: ${errorMsg}`);
+    }
     process.exit(1);
   }
 }
 async function promote(config, deploymentId) {
   const baseStorageUrl = `${config.baseUrl}/v1/public/storages/webs/${config.storageId}`;
-  const headers = { "X-Public-Key": config.publicKey };
+  const headers = storageAdminHeaders(config);
   info(
     deploymentId ? `release ${deploymentId} \uB97C production \uC73C\uB85C \uC2B9\uACA9\uD569\uB2C8\uB2E4...` : "\uCD5C\uC2E0 \uBC30\uD3EC\uB97C production \uC73C\uB85C \uC2B9\uACA9\uD569\uB2C8\uB2E4..."
   );
@@ -925,7 +963,9 @@ async function promote(config, deploymentId) {
   if (res.status < 200 || res.status >= 300) {
     const data2 = res.data;
     const msg = typeof data2 === "object" && data2 !== null ? data2.error || data2.message || JSON.stringify(data2) : `HTTP ${res.status}`;
-    error(`promote \uC2E4\uD328: ${msg}`);
+    if (!reportDeployAuthError(res.status, res.data)) {
+      error(`promote \uC2E4\uD328: ${msg}`);
+    }
     process.exit(1);
   }
   const data = res.data;
@@ -938,7 +978,7 @@ ${colors.cyan}Production: ${data.production_url}${colors.reset}
 }
 async function listReleases(config) {
   const baseStorageUrl = `${config.baseUrl}/v1/public/storages/webs/${config.storageId}`;
-  const headers = { "X-Public-Key": config.publicKey };
+  const headers = storageAdminHeaders(config);
   const res = await makeRequest(
     `${baseStorageUrl}/deployments`,
     "GET",
@@ -947,7 +987,9 @@ async function listReleases(config) {
   if (res.status < 200 || res.status >= 300) {
     const data2 = res.data;
     const msg = typeof data2 === "object" && data2 !== null ? data2.error || data2.message || JSON.stringify(data2) : `HTTP ${res.status}`;
-    error(`\uBC30\uD3EC \uC774\uB825 \uC870\uD68C \uC2E4\uD328: ${msg}`);
+    if (!reportDeployAuthError(res.status, res.data)) {
+      error(`\uBC30\uD3EC \uC774\uB825 \uC870\uD68C \uC2E4\uD328: ${msg}`);
+    }
     process.exit(1);
   }
   const data = res.data;
@@ -1391,7 +1433,11 @@ ${colors.blue}?${colors.reset} \uC120\uD0DD (\uBC88\uD638): `
       const listRes = await makeRequest(
         `${DEFAULT_BASE_URL}/v1/public/storages/webs`,
         "GET",
-        { "X-Public-Key": publicKeyForSdk }
+        {
+          "X-Public-Key": publicKeyForSdk,
+          "X-User-Secret-Key": secretKey,
+          Authorization: `Bearer ${secretKey}`
+        }
       );
       if (listRes.status === 200) {
         const listData = listRes.data;
@@ -1429,7 +1475,11 @@ ${colors.blue}?${colors.reset} \uC120\uD0DD (\uBC88\uD638): `
           const createRes = await makeRequest(
             `${DEFAULT_BASE_URL}/v1/public/storages/webs`,
             "POST",
-            { "X-Public-Key": publicKeyForSdk },
+            {
+              "X-Public-Key": publicKeyForSdk,
+              "X-User-Secret-Key": secretKey,
+              Authorization: `Bearer ${secretKey}`
+            },
             JSON.stringify({ name })
           );
           if (createRes.status !== 200) {
@@ -3434,7 +3484,7 @@ ${colors.yellow}\uBE60\uB978 \uC2DC\uC791:${colors.reset}
 
 ${colors.yellow}\uD658\uACBD\uBCC0\uC218:${colors.reset}
   CONNECTBASE_PUBLIC_KEY    Public Key (cb_pk_*)
-  CONNECTBASE_SECRET_KEY    Secret Key (cb_sk_*, \uD130\uB110\uC6A9)
+  CONNECTBASE_SECRET_KEY    Secret Key (cb_sk_*) \u2014 \uBC30\uD3EC/\uC2B9\uACA9/\uD130\uB110\uC5D0 \uD544\uC218
   CONNECTBASE_PUBLIC_KEY       (deprecated) \uB808\uAC70\uC2DC \u2014 publicKey \uB610\uB294 secretKey \uB85C \uC0AC\uC6A9
   CONNECTBASE_STORAGE_ID    \uC2A4\uD1A0\uB9AC\uC9C0 ID
   CONNECTBASE_BASE_URL      \uC11C\uBC84 URL
@@ -3672,5 +3722,6 @@ main().catch((err) => {
   normalizeRelativePath,
   parseArgs,
   registerEndpointBinding,
-  sha256Hex
+  sha256Hex,
+  storageAdminHeaders
 });