connectbase-client 3.29.0 → 3.31.0

package/dist/index.d.mts

@@ -122,6 +122,13 @@ interface HttpClientConfig {
      * 서버 환경에서만 사용 (전체 권한, 절대 노출 금지).
      */
     secretKey?: string;
+    /**
+     * 이 클라이언트가 속한 앱 ID (선택). 설정 시, refresh 응답이 **다른 앱**의 access token 을
+     * 돌려주면(예: 같은 브라우저의 다른 앱 세션 쿠키로 복구된 토큰) 해당 토큰을 채택하지 않고
+     * 세션 없음으로 처리한다. 백엔드 re-issue 가 app-scoped 가드로 1차 차단하지만, SDK 측에서도
+     * 방어적으로 한 번 더 막는다 (platform-issue 019e86d1). appId 미설정 시 이 가드는 비활성.
+     */
+    appId?: string;
     accessToken?: string;
     refreshToken?: string;
     /**
@@ -3840,6 +3847,12 @@ declare function escapeToExternalBrowser(currentUrl?: string): boolean;
  */
 declare class OAuthAPI {
     private http;
+    /**
+     * 부팅 안전망(consumeRedirectCallbackOnBoot)이 리다이렉트 콜백을 자동 소비했을 때의 promise.
+     * 앱이 그 후 `getCallbackResult()` 를 호출해도 중복으로 `bootstrapRefreshCookie` 를
+     * 발화하지 않도록 이 promise 를 공유한다 (이중 re-issue/rotation 방지).
+     */
+    private bootConsumePromise;
     constructor(http: HttpClient);
     /**
      * 활성화된 OAuth 프로바이더 목록 조회
@@ -3964,6 +3977,28 @@ declare class OAuthAPI {
         state?: string;
         error?: string;
     } | null>;
+    /**
+     * (SDK 내부용 — `ConnectBase` 생성자가 호출) 부팅 안전망.
+     *
+     * OAuth 리다이렉트 콜백 페이지에서 앱이 `getCallbackResult()` 를 호출하지 않아도,
+     * `new ConnectBase()` 만으로 URL 의 토큰(`?access_token=&refresh_token=&member_id=`)을
+     * 적재해 세션을 확립한다.
+     *
+     * **왜 필요한가:** 정적 호스팅(웹 스토리지)은 SPA fallback 으로 `/auth/callback` 같은 콜백
+     * 경로에 홈 `index.html` 을 서빙한다. 그 페이지가 콜백을 처리하지 않으면 URL 토큰이 영영
+     * 소비되지 않아 "로그인 → 다시 로그인 페이지" 무한 루프가 발생한다 (여러 사용자 동시 보고).
+     * 이 안전망은 콜백 처리 코드를 빠뜨린 앱도 동작하게 한다.
+     *
+     * **token rotation race(2026-05-16) 가 없는 이유:** 사전 `re-issue`(cookie 복구) 없이 URL
+     * 토큰을 *직접* 소비한다 — `getCallbackResult()` 의 리다이렉트 경로와 동일한 동작이다. 팝업
+     * (`window.opener` 존재)은 `ConnectBase` 생성자에서 제외되어 호출되지 않는다 (팝업 콜백은
+     * `getCallbackResult()` 의 postMessage 경로 전담). code-only(`?code=`)·에러(`?error=`)
+     * 콜백도 생성자에서 제외된다 (네트워크 교환/에러 분기는 앱이 명시 호출).
+     *
+     * @returns 토큰 적재 성공 시 true, no-op(토큰 없음 등)이면 false.
+     */
+    consumeRedirectCallbackOnBoot(): Promise<boolean>;
+    private doConsumeRedirectOnBoot;
     /**
      * 콜백 URL 에서 1회용 `code` 를 토큰으로 교환합니다 (`OAUTH_CODE_ONLY` 서버 모드용).
      *
@@ -8805,9 +8840,18 @@ declare class ConnectBase {
      *
      * `?access_token=...&refresh_token=...` (legacy 토큰-in-URL 흐름) 또는
      * `?code=...` (OAUTH_CODE_ONLY 흐름) 또는 OAuth 에러 응답 (`?error=...&state=...`)
-     * 패턴이면 true. 콜백 페이지에서 `autoRestoreSession` 을 건너뛰어 rotation race 를 피한다.
+     * 패턴이면 true. 콜백 페이지에서 일반 `autoRestoreSession` 을 건너뛰어 rotation race 를 피한다.
      */
     private isOAuthCallbackUrl;
+    /**
+     * 현재 페이지가 토큰-in-URL OAuth 리다이렉트 콜백(팝업 아님)인지 판별.
+     *
+     * `?access_token=&refresh_token=` 이 있고 `window.opener` 가 없으면 true — 부팅 안전망
+     * (`oauth.consumeRedirectCallbackOnBoot`)으로 토큰을 자동 소비할 대상이다. 팝업 콜백
+     * (`window.opener` 존재)은 `getCallbackResult()` 의 postMessage 경로가 전담하므로 제외한다.
+     * code-only(`?code=`)·에러(`?error=`) 콜백도 제외(네트워크 교환/에러 분기는 앱이 명시 호출).
+     */
+    private isOAuthRedirectCallbackUrl;
     /**
      * 새로고침/탭 재개 후 cookie 만으로 세션을 복원한다 (브라우저 전용).
      *

package/dist/index.d.ts

@@ -122,6 +122,13 @@ interface HttpClientConfig {
      * 서버 환경에서만 사용 (전체 권한, 절대 노출 금지).
      */
     secretKey?: string;
+    /**
+     * 이 클라이언트가 속한 앱 ID (선택). 설정 시, refresh 응답이 **다른 앱**의 access token 을
+     * 돌려주면(예: 같은 브라우저의 다른 앱 세션 쿠키로 복구된 토큰) 해당 토큰을 채택하지 않고
+     * 세션 없음으로 처리한다. 백엔드 re-issue 가 app-scoped 가드로 1차 차단하지만, SDK 측에서도
+     * 방어적으로 한 번 더 막는다 (platform-issue 019e86d1). appId 미설정 시 이 가드는 비활성.
+     */
+    appId?: string;
     accessToken?: string;
     refreshToken?: string;
     /**
@@ -3840,6 +3847,12 @@ declare function escapeToExternalBrowser(currentUrl?: string): boolean;
  */
 declare class OAuthAPI {
     private http;
+    /**
+     * 부팅 안전망(consumeRedirectCallbackOnBoot)이 리다이렉트 콜백을 자동 소비했을 때의 promise.
+     * 앱이 그 후 `getCallbackResult()` 를 호출해도 중복으로 `bootstrapRefreshCookie` 를
+     * 발화하지 않도록 이 promise 를 공유한다 (이중 re-issue/rotation 방지).
+     */
+    private bootConsumePromise;
     constructor(http: HttpClient);
     /**
      * 활성화된 OAuth 프로바이더 목록 조회
@@ -3964,6 +3977,28 @@ declare class OAuthAPI {
         state?: string;
         error?: string;
     } | null>;
+    /**
+     * (SDK 내부용 — `ConnectBase` 생성자가 호출) 부팅 안전망.
+     *
+     * OAuth 리다이렉트 콜백 페이지에서 앱이 `getCallbackResult()` 를 호출하지 않아도,
+     * `new ConnectBase()` 만으로 URL 의 토큰(`?access_token=&refresh_token=&member_id=`)을
+     * 적재해 세션을 확립한다.
+     *
+     * **왜 필요한가:** 정적 호스팅(웹 스토리지)은 SPA fallback 으로 `/auth/callback` 같은 콜백
+     * 경로에 홈 `index.html` 을 서빙한다. 그 페이지가 콜백을 처리하지 않으면 URL 토큰이 영영
+     * 소비되지 않아 "로그인 → 다시 로그인 페이지" 무한 루프가 발생한다 (여러 사용자 동시 보고).
+     * 이 안전망은 콜백 처리 코드를 빠뜨린 앱도 동작하게 한다.
+     *
+     * **token rotation race(2026-05-16) 가 없는 이유:** 사전 `re-issue`(cookie 복구) 없이 URL
+     * 토큰을 *직접* 소비한다 — `getCallbackResult()` 의 리다이렉트 경로와 동일한 동작이다. 팝업
+     * (`window.opener` 존재)은 `ConnectBase` 생성자에서 제외되어 호출되지 않는다 (팝업 콜백은
+     * `getCallbackResult()` 의 postMessage 경로 전담). code-only(`?code=`)·에러(`?error=`)
+     * 콜백도 생성자에서 제외된다 (네트워크 교환/에러 분기는 앱이 명시 호출).
+     *
+     * @returns 토큰 적재 성공 시 true, no-op(토큰 없음 등)이면 false.
+     */
+    consumeRedirectCallbackOnBoot(): Promise<boolean>;
+    private doConsumeRedirectOnBoot;
     /**
      * 콜백 URL 에서 1회용 `code` 를 토큰으로 교환합니다 (`OAUTH_CODE_ONLY` 서버 모드용).
      *
@@ -8805,9 +8840,18 @@ declare class ConnectBase {
      *
      * `?access_token=...&refresh_token=...` (legacy 토큰-in-URL 흐름) 또는
      * `?code=...` (OAUTH_CODE_ONLY 흐름) 또는 OAuth 에러 응답 (`?error=...&state=...`)
-     * 패턴이면 true. 콜백 페이지에서 `autoRestoreSession` 을 건너뛰어 rotation race 를 피한다.
+     * 패턴이면 true. 콜백 페이지에서 일반 `autoRestoreSession` 을 건너뛰어 rotation race 를 피한다.
      */
     private isOAuthCallbackUrl;
+    /**
+     * 현재 페이지가 토큰-in-URL OAuth 리다이렉트 콜백(팝업 아님)인지 판별.
+     *
+     * `?access_token=&refresh_token=` 이 있고 `window.opener` 가 없으면 true — 부팅 안전망
+     * (`oauth.consumeRedirectCallbackOnBoot`)으로 토큰을 자동 소비할 대상이다. 팝업 콜백
+     * (`window.opener` 존재)은 `getCallbackResult()` 의 postMessage 경로가 전담하므로 제외한다.
+     * code-only(`?code=`)·에러(`?error=`) 콜백도 제외(네트워크 교환/에러 분기는 앱이 명시 호출).
+     */
+    private isOAuthRedirectCallbackUrl;
     /**
      * 새로고침/탭 재개 후 cookie 만으로 세션을 복원한다 (브라우저 전용).
      *

package/dist/index.js

@@ -451,6 +451,15 @@ var HttpClient = class {
           this.refreshLockedUntil = 0;
           return null;
         }
+        if (this.config.appId) {
+          const tokenAppId = decodeJwtPayload(data.access_token)?.app_id;
+          if (typeof tokenAppId === "string" && tokenAppId !== this.config.appId) {
+            this.clearTokens();
+            this.refreshFailureCount = 0;
+            this.refreshLockedUntil = 0;
+            return null;
+          }
+        }
         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);
@@ -4801,6 +4810,12 @@ function escapeToExternalBrowser(currentUrl) {
 var OAuthAPI = class {
   constructor(http) {
     this.http = http;
+    /**
+     * 부팅 안전망(consumeRedirectCallbackOnBoot)이 리다이렉트 콜백을 자동 소비했을 때의 promise.
+     * 앱이 그 후 `getCallbackResult()` 를 호출해도 중복으로 `bootstrapRefreshCookie` 를
+     * 발화하지 않도록 이 promise 를 공유한다 (이중 re-issue/rotation 방지).
+     */
+    this.bootConsumePromise = null;
   }
   /**
    * 활성화된 OAuth 프로바이더 목록 조회
@@ -5095,10 +5110,58 @@ var OAuthAPI = class {
       window.close();
       return result;
     }
+    if (this.bootConsumePromise) {
+      const consumed = await this.bootConsumePromise;
+      if (consumed) {
+        return result;
+      }
+    }
     this.http.setTokens(accessToken, refreshToken);
     await this.http.bootstrapRefreshCookie();
     return result;
   }
+  /**
+   * (SDK 내부용 — `ConnectBase` 생성자가 호출) 부팅 안전망.
+   *
+   * OAuth 리다이렉트 콜백 페이지에서 앱이 `getCallbackResult()` 를 호출하지 않아도,
+   * `new ConnectBase()` 만으로 URL 의 토큰(`?access_token=&refresh_token=&member_id=`)을
+   * 적재해 세션을 확립한다.
+   *
+   * **왜 필요한가:** 정적 호스팅(웹 스토리지)은 SPA fallback 으로 `/auth/callback` 같은 콜백
+   * 경로에 홈 `index.html` 을 서빙한다. 그 페이지가 콜백을 처리하지 않으면 URL 토큰이 영영
+   * 소비되지 않아 "로그인 → 다시 로그인 페이지" 무한 루프가 발생한다 (여러 사용자 동시 보고).
+   * 이 안전망은 콜백 처리 코드를 빠뜨린 앱도 동작하게 한다.
+   *
+   * **token rotation race(2026-05-16) 가 없는 이유:** 사전 `re-issue`(cookie 복구) 없이 URL
+   * 토큰을 *직접* 소비한다 — `getCallbackResult()` 의 리다이렉트 경로와 동일한 동작이다. 팝업
+   * (`window.opener` 존재)은 `ConnectBase` 생성자에서 제외되어 호출되지 않는다 (팝업 콜백은
+   * `getCallbackResult()` 의 postMessage 경로 전담). code-only(`?code=`)·에러(`?error=`)
+   * 콜백도 생성자에서 제외된다 (네트워크 교환/에러 분기는 앱이 명시 호출).
+   *
+   * @returns 토큰 적재 성공 시 true, no-op(토큰 없음 등)이면 false.
+   */
+  consumeRedirectCallbackOnBoot() {
+    if (!this.bootConsumePromise) {
+      this.bootConsumePromise = this.doConsumeRedirectOnBoot();
+    }
+    return this.bootConsumePromise;
+  }
+  async doConsumeRedirectOnBoot() {
+    try {
+      if (typeof window === "undefined" || !window.location) return false;
+      const params = new URLSearchParams(window.location.search);
+      if (params.get("error")) return false;
+      const accessToken = params.get("access_token");
+      const refreshToken = params.get("refresh_token");
+      const memberId = params.get("member_id");
+      if (!accessToken || !refreshToken || !memberId) return false;
+      this.http.setTokens(accessToken, refreshToken);
+      await this.http.bootstrapRefreshCookie();
+      return true;
+    } catch {
+      return false;
+    }
+  }
   /**
    * 콜백 URL 에서 1회용 `code` 를 토큰으로 교환합니다 (`OAUTH_CODE_ONLY` 서버 모드용).
    *
@@ -10826,6 +10889,7 @@ var ConnectBase = class {
       baseUrl: config.baseUrl || env("CB_BASE_URL") || DEFAULT_BASE_URL,
       publicKey: config.publicKey,
       secretKey: config.secretKey,
+      appId: config.appId,
       persistence: config.persistence,
       autoRestoreSession: config.autoRestoreSession,
       requestTimeoutMs: config.requestTimeoutMs,
@@ -10860,8 +10924,12 @@ var ConnectBase = class {
     this.support = new SupportAPI(this.http);
     this.auth._attachAnalytics(this.analytics);
     const shouldAutoRestore = config.autoRestoreSession ?? true;
-    if (shouldAutoRestore && typeof window !== "undefined" && !this.isOAuthCallbackUrl()) {
-      this.http.setBootRestorePromise(this.http.tryRestoreSessionFromCookie());
+    if (shouldAutoRestore && typeof window !== "undefined") {
+      if (this.isOAuthRedirectCallbackUrl()) {
+        this.http.setBootRestorePromise(this.oauth.consumeRedirectCallbackOnBoot());
+      } else if (!this.isOAuthCallbackUrl()) {
+        this.http.setBootRestorePromise(this.http.tryRestoreSessionFromCookie());
+      }
     }
   }
   /**
@@ -10869,7 +10937,7 @@ var ConnectBase = class {
    *
    * `?access_token=...&refresh_token=...` (legacy 토큰-in-URL 흐름) 또는
    * `?code=...` (OAUTH_CODE_ONLY 흐름) 또는 OAuth 에러 응답 (`?error=...&state=...`)
-   * 패턴이면 true. 콜백 페이지에서 `autoRestoreSession` 을 건너뛰어 rotation race 를 피한다.
+   * 패턴이면 true. 콜백 페이지에서 일반 `autoRestoreSession` 을 건너뛰어 rotation race 를 피한다.
    */
   isOAuthCallbackUrl() {
     if (typeof window === "undefined" || !window.location) return false;
@@ -10879,6 +10947,20 @@ var ConnectBase = class {
     if (params.has("error") && params.has("state")) return true;
     return false;
   }
+  /**
+   * 현재 페이지가 토큰-in-URL OAuth 리다이렉트 콜백(팝업 아님)인지 판별.
+   *
+   * `?access_token=&refresh_token=` 이 있고 `window.opener` 가 없으면 true — 부팅 안전망
+   * (`oauth.consumeRedirectCallbackOnBoot`)으로 토큰을 자동 소비할 대상이다. 팝업 콜백
+   * (`window.opener` 존재)은 `getCallbackResult()` 의 postMessage 경로가 전담하므로 제외한다.
+   * code-only(`?code=`)·에러(`?error=`) 콜백도 제외(네트워크 교환/에러 분기는 앱이 명시 호출).
+   */
+  isOAuthRedirectCallbackUrl() {
+    if (typeof window === "undefined" || !window.location) return false;
+    if (window.opener) return false;
+    const params = new URLSearchParams(window.location.search);
+    return params.has("access_token") && params.has("refresh_token");
+  }
   /**
    * 새로고침/탭 재개 후 cookie 만으로 세션을 복원한다 (브라우저 전용).
    *

package/dist/index.mjs

@@ -405,6 +405,15 @@ var HttpClient = class {
           this.refreshLockedUntil = 0;
           return null;
         }
+        if (this.config.appId) {
+          const tokenAppId = decodeJwtPayload(data.access_token)?.app_id;
+          if (typeof tokenAppId === "string" && tokenAppId !== this.config.appId) {
+            this.clearTokens();
+            this.refreshFailureCount = 0;
+            this.refreshLockedUntil = 0;
+            return null;
+          }
+        }
         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);
@@ -4755,6 +4764,12 @@ function escapeToExternalBrowser(currentUrl) {
 var OAuthAPI = class {
   constructor(http) {
     this.http = http;
+    /**
+     * 부팅 안전망(consumeRedirectCallbackOnBoot)이 리다이렉트 콜백을 자동 소비했을 때의 promise.
+     * 앱이 그 후 `getCallbackResult()` 를 호출해도 중복으로 `bootstrapRefreshCookie` 를
+     * 발화하지 않도록 이 promise 를 공유한다 (이중 re-issue/rotation 방지).
+     */
+    this.bootConsumePromise = null;
   }
   /**
    * 활성화된 OAuth 프로바이더 목록 조회
@@ -5049,10 +5064,58 @@ var OAuthAPI = class {
       window.close();
       return result;
     }
+    if (this.bootConsumePromise) {
+      const consumed = await this.bootConsumePromise;
+      if (consumed) {
+        return result;
+      }
+    }
     this.http.setTokens(accessToken, refreshToken);
     await this.http.bootstrapRefreshCookie();
     return result;
   }
+  /**
+   * (SDK 내부용 — `ConnectBase` 생성자가 호출) 부팅 안전망.
+   *
+   * OAuth 리다이렉트 콜백 페이지에서 앱이 `getCallbackResult()` 를 호출하지 않아도,
+   * `new ConnectBase()` 만으로 URL 의 토큰(`?access_token=&refresh_token=&member_id=`)을
+   * 적재해 세션을 확립한다.
+   *
+   * **왜 필요한가:** 정적 호스팅(웹 스토리지)은 SPA fallback 으로 `/auth/callback` 같은 콜백
+   * 경로에 홈 `index.html` 을 서빙한다. 그 페이지가 콜백을 처리하지 않으면 URL 토큰이 영영
+   * 소비되지 않아 "로그인 → 다시 로그인 페이지" 무한 루프가 발생한다 (여러 사용자 동시 보고).
+   * 이 안전망은 콜백 처리 코드를 빠뜨린 앱도 동작하게 한다.
+   *
+   * **token rotation race(2026-05-16) 가 없는 이유:** 사전 `re-issue`(cookie 복구) 없이 URL
+   * 토큰을 *직접* 소비한다 — `getCallbackResult()` 의 리다이렉트 경로와 동일한 동작이다. 팝업
+   * (`window.opener` 존재)은 `ConnectBase` 생성자에서 제외되어 호출되지 않는다 (팝업 콜백은
+   * `getCallbackResult()` 의 postMessage 경로 전담). code-only(`?code=`)·에러(`?error=`)
+   * 콜백도 생성자에서 제외된다 (네트워크 교환/에러 분기는 앱이 명시 호출).
+   *
+   * @returns 토큰 적재 성공 시 true, no-op(토큰 없음 등)이면 false.
+   */
+  consumeRedirectCallbackOnBoot() {
+    if (!this.bootConsumePromise) {
+      this.bootConsumePromise = this.doConsumeRedirectOnBoot();
+    }
+    return this.bootConsumePromise;
+  }
+  async doConsumeRedirectOnBoot() {
+    try {
+      if (typeof window === "undefined" || !window.location) return false;
+      const params = new URLSearchParams(window.location.search);
+      if (params.get("error")) return false;
+      const accessToken = params.get("access_token");
+      const refreshToken = params.get("refresh_token");
+      const memberId = params.get("member_id");
+      if (!accessToken || !refreshToken || !memberId) return false;
+      this.http.setTokens(accessToken, refreshToken);
+      await this.http.bootstrapRefreshCookie();
+      return true;
+    } catch {
+      return false;
+    }
+  }
   /**
    * 콜백 URL 에서 1회용 `code` 를 토큰으로 교환합니다 (`OAUTH_CODE_ONLY` 서버 모드용).
    *
@@ -10780,6 +10843,7 @@ var ConnectBase = class {
       baseUrl: config.baseUrl || env("CB_BASE_URL") || DEFAULT_BASE_URL,
       publicKey: config.publicKey,
       secretKey: config.secretKey,
+      appId: config.appId,
       persistence: config.persistence,
       autoRestoreSession: config.autoRestoreSession,
       requestTimeoutMs: config.requestTimeoutMs,
@@ -10814,8 +10878,12 @@ var ConnectBase = class {
     this.support = new SupportAPI(this.http);
     this.auth._attachAnalytics(this.analytics);
     const shouldAutoRestore = config.autoRestoreSession ?? true;
-    if (shouldAutoRestore && typeof window !== "undefined" && !this.isOAuthCallbackUrl()) {
-      this.http.setBootRestorePromise(this.http.tryRestoreSessionFromCookie());
+    if (shouldAutoRestore && typeof window !== "undefined") {
+      if (this.isOAuthRedirectCallbackUrl()) {
+        this.http.setBootRestorePromise(this.oauth.consumeRedirectCallbackOnBoot());
+      } else if (!this.isOAuthCallbackUrl()) {
+        this.http.setBootRestorePromise(this.http.tryRestoreSessionFromCookie());
+      }
     }
   }
   /**
@@ -10823,7 +10891,7 @@ var ConnectBase = class {
    *
    * `?access_token=...&refresh_token=...` (legacy 토큰-in-URL 흐름) 또는
    * `?code=...` (OAUTH_CODE_ONLY 흐름) 또는 OAuth 에러 응답 (`?error=...&state=...`)
-   * 패턴이면 true. 콜백 페이지에서 `autoRestoreSession` 을 건너뛰어 rotation race 를 피한다.
+   * 패턴이면 true. 콜백 페이지에서 일반 `autoRestoreSession` 을 건너뛰어 rotation race 를 피한다.
    */
   isOAuthCallbackUrl() {
     if (typeof window === "undefined" || !window.location) return false;
@@ -10833,6 +10901,20 @@ var ConnectBase = class {
     if (params.has("error") && params.has("state")) return true;
     return false;
   }
+  /**
+   * 현재 페이지가 토큰-in-URL OAuth 리다이렉트 콜백(팝업 아님)인지 판별.
+   *
+   * `?access_token=&refresh_token=` 이 있고 `window.opener` 가 없으면 true — 부팅 안전망
+   * (`oauth.consumeRedirectCallbackOnBoot`)으로 토큰을 자동 소비할 대상이다. 팝업 콜백
+   * (`window.opener` 존재)은 `getCallbackResult()` 의 postMessage 경로가 전담하므로 제외한다.
+   * code-only(`?code=`)·에러(`?error=`) 콜백도 제외(네트워크 교환/에러 분기는 앱이 명시 호출).
+   */
+  isOAuthRedirectCallbackUrl() {
+    if (typeof window === "undefined" || !window.location) return false;
+    if (window.opener) return false;
+    const params = new URLSearchParams(window.location.search);
+    return params.has("access_token") && params.has("refresh_token");
+  }
   /**
    * 새로고침/탭 재개 후 cookie 만으로 세션을 복원한다 (브라우저 전용).
    *

package/package.json

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