connectbase-client 3.7.1 → 3.8.0

package/dist/index.d.mts

@@ -35,15 +35,23 @@ interface HttpClientConfig {
     refreshToken?: string;
     /**
      * 토큰 저장 방식. **기본값은 'none' (메모리 저장)**.
-     * XSS 취약점이 하나라도 있을 경우 전 세션이 탈취되므로, 영구 저장 옵션은
-     * 위험을 이해하고 명시적으로 선택한 경우에만 사용한다.
+     * XSS 취약점이 하나라도 있을 경우 영구 저장은 즉시 전 세션 탈취로 이어지므로,
+     * 영구 저장 옵션은 위험을 이해하고 명시적으로 선택한 경우에만 사용한다.
      *
-     * - 'none' (권장·기본값): 메모리에만 저장. 새로고침 시 재로그인 필요
-     *   → 서버가 refresh token 을 HttpOnly;Secure;SameSite 쿠키로 발급하는 구성에서만 사용
-     * - 'sessionStorage': 탭 종료 시 삭제. JS 접근 가능 → XSS 로 탈취 가능
+     * - 'none' (권장·기본값): access token 만 메모리 저장. refresh token 은 서버가 발급한
+     *   HttpOnly cookie 로만 보관되어 JS 가 접근할 수 없다 (XSS 시 탈취 불가). 새로고침 후에는
+     *   `autoRestoreSession`(기본 true) 으로 cookie 만으로 자동 복구된다.
+     * - 'sessionStorage': 탭 종료 시 삭제. JS 접근 가능 → XSS 로 탭 세션 탈취 가능
      * - 'localStorage': 브라우저 종료 후에도 유지. JS 접근 가능 → XSS 로 영구 탈취 가능
      */
     persistence?: TokenPersistence;
+    /**
+     * 새로고침/탭 재개 시 HttpOnly cookie 로부터 access token 을 자동 복구할지 여부.
+     * 기본값은 브라우저 환경에서 true. 비-브라우저(Node.js, RN) 에서는 무시된다.
+     *
+     * cookie 가 없는 경우(미로그인) 조용히 실패하며 콘솔 에러를 발생시키지 않는다.
+     */
+    autoRestoreSession?: boolean;
     /**
      * 요청별 기본 타임아웃(ms). 개별 호출의 `timeout` 이 우선.
      * 기본값 30000ms. 0 또는 음수 지정 시 타임아웃 비활성화.
@@ -121,6 +129,17 @@ declare class HttpClient {
      */
     getBaseUrl(): string;
     private refreshAccessToken;
+    /**
+     * 새로고침/탭 재개 시 HttpOnly cookie 만으로 access token 을 복구한다.
+     *
+     * 동작:
+     *   - 메모리에 access token 이 이미 있으면 그대로 반환 (true).
+     *   - 없으면 `/v1/auth/re-issue` 를 cookie 만으로 호출. cookie 가 있으면 access token 회복.
+     *   - cookie 가 없거나(미로그인) 만료된 경우 조용히 false 반환 (콘솔 에러 없음).
+     *
+     * 비-브라우저 환경에서는 cookie 흐름이 없으므로 즉시 false 반환.
+     */
+    tryRestoreSessionFromCookie(): Promise<boolean>;
     private emitError;
     private isTokenExpired;
     private prepareHeaders;
@@ -7420,12 +7439,23 @@ interface ConnectBaseConfig {
     onTokenExpired?: () => void;
     /**
      * 토큰 저장 방식.
-     * - 'none' (기본·권장): 메모리에만 저장. 새로고침 시 재로그인 필요. XSS 노출 최소화
-     * - 'sessionStorage': 탭 종료 시 삭제 (XSS 시 현재 탭 세션 탈취 가능)
-     * - 'localStorage': 브라우저 종료 후에도 유지 (XSS 시 토큰 영구 탈취 가능 — 콘솔 경고 출력)
+     * - 'none' (기본·권장): access token 만 메모리. refresh token 은 서버 HttpOnly cookie 로
+     *   보관되어 JS 가 접근할 수 없음 (XSS 시 탈취 불가). 새로고침 후에는 `autoRestoreSession`
+     *   (기본 true) 으로 cookie 만으로 자동 복구.
+     * - 'sessionStorage': 탭 종료 시 삭제 (XSS 시 탭 세션 탈취 가능 — 콘솔 경고 출력)
+     * - 'localStorage': 브라우저 종료 후에도 유지 (XSS 시 영구 탈취 가능 — 콘솔 경고 출력)
      * @default 'none'
      */
     persistence?: TokenPersistence;
+    /**
+     * 새로고침/탭 재개 시 HttpOnly cookie 만으로 access token 을 자동 복구할지 여부.
+     * 브라우저 환경에서 기본 true. cookie 가 없거나 만료되었으면 조용히 실패.
+     *
+     * cookie 가 없는 미로그인 상태에서 콘솔에 401 노이즈가 찍히지 않도록 silent 처리한다.
+     *
+     * @default true (브라우저), false (Node.js / RN)
+     */
+    autoRestoreSession?: boolean;
     /**
      * 에러 트래커 설정
      */
@@ -7578,6 +7608,15 @@ declare class ConnectBase {
      */
     readonly endpoint: EndpointAPI;
     constructor(config?: ConnectBaseConfig);
+    /**
+     * 새로고침/탭 재개 후 cookie 만으로 세션을 복원한다 (브라우저 전용).
+     *
+     * 일반적으로는 ConnectBase 생성 시 `autoRestoreSession: true` (기본값) 으로 자동 호출되지만,
+     * 호출 결과를 await 해서 로그인 상태에 따라 다른 UI 를 그리고 싶다면 명시적으로 호출한다.
+     *
+     * @returns access token 복원 성공 시 true, 미로그인/cookie 만료 시 false
+     */
+    restoreSession(): Promise<boolean>;
     /**
      * 수동으로 토큰 설정 (기존 토큰으로 세션 복원 시)
      */

package/dist/index.d.ts

@@ -35,15 +35,23 @@ interface HttpClientConfig {
     refreshToken?: string;
     /**
      * 토큰 저장 방식. **기본값은 'none' (메모리 저장)**.
-     * XSS 취약점이 하나라도 있을 경우 전 세션이 탈취되므로, 영구 저장 옵션은
-     * 위험을 이해하고 명시적으로 선택한 경우에만 사용한다.
+     * XSS 취약점이 하나라도 있을 경우 영구 저장은 즉시 전 세션 탈취로 이어지므로,
+     * 영구 저장 옵션은 위험을 이해하고 명시적으로 선택한 경우에만 사용한다.
      *
-     * - 'none' (권장·기본값): 메모리에만 저장. 새로고침 시 재로그인 필요
-     *   → 서버가 refresh token 을 HttpOnly;Secure;SameSite 쿠키로 발급하는 구성에서만 사용
-     * - 'sessionStorage': 탭 종료 시 삭제. JS 접근 가능 → XSS 로 탈취 가능
+     * - 'none' (권장·기본값): access token 만 메모리 저장. refresh token 은 서버가 발급한
+     *   HttpOnly cookie 로만 보관되어 JS 가 접근할 수 없다 (XSS 시 탈취 불가). 새로고침 후에는
+     *   `autoRestoreSession`(기본 true) 으로 cookie 만으로 자동 복구된다.
+     * - 'sessionStorage': 탭 종료 시 삭제. JS 접근 가능 → XSS 로 탭 세션 탈취 가능
      * - 'localStorage': 브라우저 종료 후에도 유지. JS 접근 가능 → XSS 로 영구 탈취 가능
      */
     persistence?: TokenPersistence;
+    /**
+     * 새로고침/탭 재개 시 HttpOnly cookie 로부터 access token 을 자동 복구할지 여부.
+     * 기본값은 브라우저 환경에서 true. 비-브라우저(Node.js, RN) 에서는 무시된다.
+     *
+     * cookie 가 없는 경우(미로그인) 조용히 실패하며 콘솔 에러를 발생시키지 않는다.
+     */
+    autoRestoreSession?: boolean;
     /**
      * 요청별 기본 타임아웃(ms). 개별 호출의 `timeout` 이 우선.
      * 기본값 30000ms. 0 또는 음수 지정 시 타임아웃 비활성화.
@@ -121,6 +129,17 @@ declare class HttpClient {
      */
     getBaseUrl(): string;
     private refreshAccessToken;
+    /**
+     * 새로고침/탭 재개 시 HttpOnly cookie 만으로 access token 을 복구한다.
+     *
+     * 동작:
+     *   - 메모리에 access token 이 이미 있으면 그대로 반환 (true).
+     *   - 없으면 `/v1/auth/re-issue` 를 cookie 만으로 호출. cookie 가 있으면 access token 회복.
+     *   - cookie 가 없거나(미로그인) 만료된 경우 조용히 false 반환 (콘솔 에러 없음).
+     *
+     * 비-브라우저 환경에서는 cookie 흐름이 없으므로 즉시 false 반환.
+     */
+    tryRestoreSessionFromCookie(): Promise<boolean>;
     private emitError;
     private isTokenExpired;
     private prepareHeaders;
@@ -7420,12 +7439,23 @@ interface ConnectBaseConfig {
     onTokenExpired?: () => void;
     /**
      * 토큰 저장 방식.
-     * - 'none' (기본·권장): 메모리에만 저장. 새로고침 시 재로그인 필요. XSS 노출 최소화
-     * - 'sessionStorage': 탭 종료 시 삭제 (XSS 시 현재 탭 세션 탈취 가능)
-     * - 'localStorage': 브라우저 종료 후에도 유지 (XSS 시 토큰 영구 탈취 가능 — 콘솔 경고 출력)
+     * - 'none' (기본·권장): access token 만 메모리. refresh token 은 서버 HttpOnly cookie 로
+     *   보관되어 JS 가 접근할 수 없음 (XSS 시 탈취 불가). 새로고침 후에는 `autoRestoreSession`
+     *   (기본 true) 으로 cookie 만으로 자동 복구.
+     * - 'sessionStorage': 탭 종료 시 삭제 (XSS 시 탭 세션 탈취 가능 — 콘솔 경고 출력)
+     * - 'localStorage': 브라우저 종료 후에도 유지 (XSS 시 영구 탈취 가능 — 콘솔 경고 출력)
      * @default 'none'
      */
     persistence?: TokenPersistence;
+    /**
+     * 새로고침/탭 재개 시 HttpOnly cookie 만으로 access token 을 자동 복구할지 여부.
+     * 브라우저 환경에서 기본 true. cookie 가 없거나 만료되었으면 조용히 실패.
+     *
+     * cookie 가 없는 미로그인 상태에서 콘솔에 401 노이즈가 찍히지 않도록 silent 처리한다.
+     *
+     * @default true (브라우저), false (Node.js / RN)
+     */
+    autoRestoreSession?: boolean;
     /**
      * 에러 트래커 설정
      */
@@ -7578,6 +7608,15 @@ declare class ConnectBase {
      */
     readonly endpoint: EndpointAPI;
     constructor(config?: ConnectBaseConfig);
+    /**
+     * 새로고침/탭 재개 후 cookie 만으로 세션을 복원한다 (브라우저 전용).
+     *
+     * 일반적으로는 ConnectBase 생성 시 `autoRestoreSession: true` (기본값) 으로 자동 호출되지만,
+     * 호출 결과를 await 해서 로그인 상태에 따라 다른 UI 를 그리고 싶다면 명시적으로 호출한다.
+     *
+     * @returns access token 복원 성공 시 true, 미로그인/cookie 만료 시 false
+     */
+    restoreSession(): Promise<boolean>;
     /**
      * 수동으로 토큰 설정 (기존 토큰으로 세션 복원 시)
      */

package/dist/index.js

@@ -109,11 +109,11 @@ var HttpClient = class {
     if (typeof window === "undefined") return;
     if (this.config.persistence === "localStorage") {
       console.warn(
-        `[connect-base-client] persistence="localStorage" \uB294 XSS \uC2DC \uD1A0\uD070 \uC601\uAD6C \uD0C8\uCDE8 \uC704\uD5D8\uC774 \uC788\uC2B5\uB2C8\uB2E4. refresh token \uC740 \uC11C\uBC84 HttpOnly \uCFE0\uD0A4\uB85C \uBC1C\uAE09\uBC1B\uACE0 \uAE30\uBCF8\uAC12('none')\uC744 \uC0AC\uC6A9\uD558\uC138\uC694.`
+        `[connect-base-client] persistence="localStorage" \uB294 XSS \uC2DC refresh token \uC601\uAD6C \uD0C8\uCDE8 \uC704\uD5D8\uC774 \uC788\uC2B5\uB2C8\uB2E4. \uAE30\uBCF8\uAC12('none') \uC744 \uC0AC\uC6A9\uD558\uBA74 \uC11C\uBC84\uAC00 \uBC1C\uAE09\uD55C HttpOnly cookie \uB85C\uB9CC refresh token \uC774 \uBCF4\uAD00\uB418\uC5B4 JS \uAC00 \uC811\uADFC\uD560 \uC218 \uC5C6\uACE0, \uC0C8\uB85C\uACE0\uCE68 \uD6C4\uC5D0\uB3C4 autoRestoreSession \uC73C\uB85C \uC790\uB3D9 \uBCF5\uAD6C\uB429\uB2C8\uB2E4.`
       );
     } else if (this.config.persistence === "sessionStorage") {
       console.warn(
-        '[connect-base-client] persistence="sessionStorage" \uB294 XSS \uC2DC \uD604\uC7AC \uD0ED \uC138\uC158 \uD0C8\uCDE8 \uC704\uD5D8\uC774 \uC788\uC2B5\uB2C8\uB2E4.'
+        `[connect-base-client] persistence="sessionStorage" \uB294 XSS \uC2DC \uD0ED \uC138\uC158 \uD0C8\uCDE8 \uC704\uD5D8\uC774 \uC788\uC2B5\uB2C8\uB2E4. \uAE30\uBCF8\uAC12('none') + HttpOnly cookie \uD750\uB984\uC744 \uAD8C\uC7A5\uD569\uB2C8\uB2E4.`
       );
     }
   }
@@ -249,7 +249,7 @@ var HttpClient = class {
       throw error;
     }
     this.isRefreshing = true;
-    if (!this.config.refreshToken) {
+    if (!this.config.refreshToken && typeof window === "undefined") {
       this.isRefreshing = false;
       this.config.onTokenExpired?.();
       const error = new AuthError("Refresh token is missing. Please login again.");
@@ -262,22 +262,35 @@ var HttpClient = class {
         timeout: this.config.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS
       });
       try {
+        const headers = {
+          "Content-Type": "application/json"
+        };
+        if (this.config.refreshToken) {
+          headers.Authorization = `Bearer ${this.config.refreshToken}`;
+        }
         const response = await fetch(`${this.config.baseUrl}/v1/auth/re-issue`, {
           method: "POST",
-          headers: {
-            "Content-Type": "application/json",
-            "Authorization": `Bearer ${this.config.refreshToken}`
-          },
+          headers,
+          credentials: "include",
           signal
         });
         if (!response.ok) {
           throw new Error("Token refresh failed");
         }
         const data = await response.json();
-        this.setTokens(data.access_token, data.refresh_token);
+        if (!data || typeof data.access_token !== "string") {
+          throw new Error("Token refresh response missing access_token");
+        }
+        const nextRefreshToken = typeof data.refresh_token === "string" && data.refresh_token.length > 0 ? data.refresh_token : this.config.refreshToken ?? "";
+        if (nextRefreshToken) {
+          this.setTokens(data.access_token, nextRefreshToken);
+        } else {
+          this.config.accessToken = data.access_token;
+          this.persistTokens();
+        }
         this.config.onTokenRefresh?.({
           accessToken: data.access_token,
-          refreshToken: data.refresh_token
+          refreshToken: nextRefreshToken
         });
         this.refreshFailureCount = 0;
         this.refreshLockedUntil = 0;
@@ -303,6 +316,28 @@ var HttpClient = class {
     })();
     return this.refreshPromise;
   }
+  /**
+   * 새로고침/탭 재개 시 HttpOnly cookie 만으로 access token 을 복구한다.
+   *
+   * 동작:
+   *   - 메모리에 access token 이 이미 있으면 그대로 반환 (true).
+   *   - 없으면 `/v1/auth/re-issue` 를 cookie 만으로 호출. cookie 가 있으면 access token 회복.
+   *   - cookie 가 없거나(미로그인) 만료된 경우 조용히 false 반환 (콘솔 에러 없음).
+   *
+   * 비-브라우저 환경에서는 cookie 흐름이 없으므로 즉시 false 반환.
+   */
+  async tryRestoreSessionFromCookie() {
+    if (typeof window === "undefined") return false;
+    if (this.config.accessToken && !this.isTokenExpired(this.config.accessToken)) {
+      return true;
+    }
+    try {
+      const newAccessToken = await this.refreshAccessToken();
+      return !!newAccessToken;
+    } catch {
+      return false;
+    }
+  }
   emitError(error) {
     try {
       this.config.onError?.(error);
@@ -402,6 +437,7 @@ var HttpClient = class {
     try {
       const response = await fetch(`${this.config.baseUrl}${url}`, {
         ...init,
+        credentials: "include",
         signal
       });
       return await this.handleResponse(response);
@@ -470,6 +506,7 @@ var HttpClient = class {
     }
     return fetch(`${this.config.baseUrl}${url}`, {
       ...init,
+      credentials: "include",
       headers: mergedHeaders
     });
   }
@@ -9600,6 +9637,7 @@ var ConnectBase = class {
       publicKey: config.publicKey,
       secretKey: config.secretKey,
       persistence: config.persistence,
+      autoRestoreSession: config.autoRestoreSession,
       requestTimeoutMs: config.requestTimeoutMs,
       onError: config.onError,
       onTokenRefresh: config.onTokenRefresh,
@@ -9629,6 +9667,21 @@ var ConnectBase = class {
     this.analytics = new AnalyticsAPI(this.http);
     this.endpoint = new EndpointAPI(this.http);
     this.auth._attachAnalytics(this.analytics);
+    const shouldAutoRestore = config.autoRestoreSession ?? true;
+    if (shouldAutoRestore && typeof window !== "undefined") {
+      void this.http.tryRestoreSessionFromCookie();
+    }
+  }
+  /**
+   * 새로고침/탭 재개 후 cookie 만으로 세션을 복원한다 (브라우저 전용).
+   *
+   * 일반적으로는 ConnectBase 생성 시 `autoRestoreSession: true` (기본값) 으로 자동 호출되지만,
+   * 호출 결과를 await 해서 로그인 상태에 따라 다른 UI 를 그리고 싶다면 명시적으로 호출한다.
+   *
+   * @returns access token 복원 성공 시 true, 미로그인/cookie 만료 시 false
+   */
+  async restoreSession() {
+    return this.http.tryRestoreSessionFromCookie();
   }
   /**
    * 수동으로 토큰 설정 (기존 토큰으로 세션 복원 시)

package/dist/index.mjs

@@ -68,11 +68,11 @@ var HttpClient = class {
     if (typeof window === "undefined") return;
     if (this.config.persistence === "localStorage") {
       console.warn(
-        `[connect-base-client] persistence="localStorage" \uB294 XSS \uC2DC \uD1A0\uD070 \uC601\uAD6C \uD0C8\uCDE8 \uC704\uD5D8\uC774 \uC788\uC2B5\uB2C8\uB2E4. refresh token \uC740 \uC11C\uBC84 HttpOnly \uCFE0\uD0A4\uB85C \uBC1C\uAE09\uBC1B\uACE0 \uAE30\uBCF8\uAC12('none')\uC744 \uC0AC\uC6A9\uD558\uC138\uC694.`
+        `[connect-base-client] persistence="localStorage" \uB294 XSS \uC2DC refresh token \uC601\uAD6C \uD0C8\uCDE8 \uC704\uD5D8\uC774 \uC788\uC2B5\uB2C8\uB2E4. \uAE30\uBCF8\uAC12('none') \uC744 \uC0AC\uC6A9\uD558\uBA74 \uC11C\uBC84\uAC00 \uBC1C\uAE09\uD55C HttpOnly cookie \uB85C\uB9CC refresh token \uC774 \uBCF4\uAD00\uB418\uC5B4 JS \uAC00 \uC811\uADFC\uD560 \uC218 \uC5C6\uACE0, \uC0C8\uB85C\uACE0\uCE68 \uD6C4\uC5D0\uB3C4 autoRestoreSession \uC73C\uB85C \uC790\uB3D9 \uBCF5\uAD6C\uB429\uB2C8\uB2E4.`
       );
     } else if (this.config.persistence === "sessionStorage") {
       console.warn(
-        '[connect-base-client] persistence="sessionStorage" \uB294 XSS \uC2DC \uD604\uC7AC \uD0ED \uC138\uC158 \uD0C8\uCDE8 \uC704\uD5D8\uC774 \uC788\uC2B5\uB2C8\uB2E4.'
+        `[connect-base-client] persistence="sessionStorage" \uB294 XSS \uC2DC \uD0ED \uC138\uC158 \uD0C8\uCDE8 \uC704\uD5D8\uC774 \uC788\uC2B5\uB2C8\uB2E4. \uAE30\uBCF8\uAC12('none') + HttpOnly cookie \uD750\uB984\uC744 \uAD8C\uC7A5\uD569\uB2C8\uB2E4.`
       );
     }
   }
@@ -208,7 +208,7 @@ var HttpClient = class {
       throw error;
     }
     this.isRefreshing = true;
-    if (!this.config.refreshToken) {
+    if (!this.config.refreshToken && typeof window === "undefined") {
       this.isRefreshing = false;
       this.config.onTokenExpired?.();
       const error = new AuthError("Refresh token is missing. Please login again.");
@@ -221,22 +221,35 @@ var HttpClient = class {
         timeout: this.config.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS
       });
       try {
+        const headers = {
+          "Content-Type": "application/json"
+        };
+        if (this.config.refreshToken) {
+          headers.Authorization = `Bearer ${this.config.refreshToken}`;
+        }
         const response = await fetch(`${this.config.baseUrl}/v1/auth/re-issue`, {
           method: "POST",
-          headers: {
-            "Content-Type": "application/json",
-            "Authorization": `Bearer ${this.config.refreshToken}`
-          },
+          headers,
+          credentials: "include",
           signal
         });
         if (!response.ok) {
           throw new Error("Token refresh failed");
         }
         const data = await response.json();
-        this.setTokens(data.access_token, data.refresh_token);
+        if (!data || typeof data.access_token !== "string") {
+          throw new Error("Token refresh response missing access_token");
+        }
+        const nextRefreshToken = typeof data.refresh_token === "string" && data.refresh_token.length > 0 ? data.refresh_token : this.config.refreshToken ?? "";
+        if (nextRefreshToken) {
+          this.setTokens(data.access_token, nextRefreshToken);
+        } else {
+          this.config.accessToken = data.access_token;
+          this.persistTokens();
+        }
         this.config.onTokenRefresh?.({
           accessToken: data.access_token,
-          refreshToken: data.refresh_token
+          refreshToken: nextRefreshToken
         });
         this.refreshFailureCount = 0;
         this.refreshLockedUntil = 0;
@@ -262,6 +275,28 @@ var HttpClient = class {
     })();
     return this.refreshPromise;
   }
+  /**
+   * 새로고침/탭 재개 시 HttpOnly cookie 만으로 access token 을 복구한다.
+   *
+   * 동작:
+   *   - 메모리에 access token 이 이미 있으면 그대로 반환 (true).
+   *   - 없으면 `/v1/auth/re-issue` 를 cookie 만으로 호출. cookie 가 있으면 access token 회복.
+   *   - cookie 가 없거나(미로그인) 만료된 경우 조용히 false 반환 (콘솔 에러 없음).
+   *
+   * 비-브라우저 환경에서는 cookie 흐름이 없으므로 즉시 false 반환.
+   */
+  async tryRestoreSessionFromCookie() {
+    if (typeof window === "undefined") return false;
+    if (this.config.accessToken && !this.isTokenExpired(this.config.accessToken)) {
+      return true;
+    }
+    try {
+      const newAccessToken = await this.refreshAccessToken();
+      return !!newAccessToken;
+    } catch {
+      return false;
+    }
+  }
   emitError(error) {
     try {
       this.config.onError?.(error);
@@ -361,6 +396,7 @@ var HttpClient = class {
     try {
       const response = await fetch(`${this.config.baseUrl}${url}`, {
         ...init,
+        credentials: "include",
         signal
       });
       return await this.handleResponse(response);
@@ -429,6 +465,7 @@ var HttpClient = class {
     }
     return fetch(`${this.config.baseUrl}${url}`, {
       ...init,
+      credentials: "include",
       headers: mergedHeaders
     });
   }
@@ -9559,6 +9596,7 @@ var ConnectBase = class {
       publicKey: config.publicKey,
       secretKey: config.secretKey,
       persistence: config.persistence,
+      autoRestoreSession: config.autoRestoreSession,
       requestTimeoutMs: config.requestTimeoutMs,
       onError: config.onError,
       onTokenRefresh: config.onTokenRefresh,
@@ -9588,6 +9626,21 @@ var ConnectBase = class {
     this.analytics = new AnalyticsAPI(this.http);
     this.endpoint = new EndpointAPI(this.http);
     this.auth._attachAnalytics(this.analytics);
+    const shouldAutoRestore = config.autoRestoreSession ?? true;
+    if (shouldAutoRestore && typeof window !== "undefined") {
+      void this.http.tryRestoreSessionFromCookie();
+    }
+  }
+  /**
+   * 새로고침/탭 재개 후 cookie 만으로 세션을 복원한다 (브라우저 전용).
+   *
+   * 일반적으로는 ConnectBase 생성 시 `autoRestoreSession: true` (기본값) 으로 자동 호출되지만,
+   * 호출 결과를 await 해서 로그인 상태에 따라 다른 UI 를 그리고 싶다면 명시적으로 호출한다.
+   *
+   * @returns access token 복원 성공 시 true, 미로그인/cookie 만료 시 false
+   */
+  async restoreSession() {
+    return this.http.tryRestoreSessionFromCookie();
   }
   /**
    * 수동으로 토큰 설정 (기존 토큰으로 세션 복원 시)

package/package.json

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