@vibexnpm/talkx 7.3.0 → 8.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@vibexnpm/talkx",
-    "version": "7.3.0",
+    "version": "8.0.0",
     "type": "module",
     "description": "TalkFlow SDK - Chat & WebRTC unified client",
     "main": "dist/talkflow-sdk.umd.js",

package/src/TalkFlowClient.js

@@ -6,6 +6,7 @@
 import EventEmitter from './utils/EventEmitter.js';
 import Logger from './utils/Logger.js';
 import ApiClient from './utils/ApiClient.js';
+import AuthSession, { tokenClaims } from './auth/AuthSession.js';
 import { extractUserIdFromJWT } from './utils/jwtUtils.js';
 import { ConnectionState, ErrorTypes, DefaultConfig, LogLevel, Environment, getServerUrl } from './constants.js';
 import { initializeSubClients, applySessionMethods } from './talkflow/session.js';
@@ -66,6 +67,7 @@ class TalkFlowClient extends EventEmitter {
             apiKey: options.apiKey,
             projectId: options.projectId,
             jwtToken: options.jwtToken || null,
+            sessionMode: options.sessionMode || (tokenClaims(options.jwtToken || '').sid ? 'refresh' : 'legacy'),
             useSockJS: options.useSockJS !== false,
             reconnectDelay: options.reconnectDelay || DefaultConfig.reconnectDelay,
             maxReconnectDelay: options.maxReconnectDelay || DefaultConfig.maxReconnectDelay,
@@ -121,6 +123,8 @@ class TalkFlowClient extends EventEmitter {
         });
 
         // ConnectionManager, ChatClient, WebRTCClient는 지연 초기화
+        this.authSession = null;
+        this._authConnectionRequested = false;
         this.connectionManager = null;
         this._chat = null;
         this._webrtc = null;
@@ -133,6 +137,7 @@ class TalkFlowClient extends EventEmitter {
         }
 
         this._initialized = true;
+        if (this.options.sessionMode === 'refresh') this._enableRefreshSession();
         this.logger.info('TalkFlowClient initialized', {
             userId: this._userId,
             hasToken: !!this.options.jwtToken
@@ -163,16 +168,16 @@ class TalkFlowClient extends EventEmitter {
         if (!options) {
             throw new Error('Options are required');
         }
-        if (!options.apiKey) {
+        if (!options.apiKey && options.sessionMode !== 'refresh') {
             throw new Error('apiKey is required');
         }
-        if (!options.projectId) {
+        if (!options.projectId && options.sessionMode !== 'refresh') {
             throw new Error('projectId is required');
         }
 
         // Server Key (sk-) 는 SDK 가 쓸 일이 없다 — 유일한 용도였던 registerUser(/users/auth) 가
         // 사라졌다. 그래도 들어오면 잘못된 키를 넣은 것이므로 알린다.
-        if (options.apiKey.startsWith('sk-')) {
+        if (options.apiKey?.startsWith('sk-')) {
             console.error(
                 '🚨 [TalkFlow] Server Key (sk-) 로 SDK 를 초기화했습니다. ' +
                 'SDK 는 Client Key (ck-) 만 사용합니다 — loginUser() 응답의 clientKey 를 그대로 쓰세요.'
@@ -204,6 +209,82 @@ class TalkFlowClient extends EventEmitter {
         return this.connectionManager ? this.connectionManager.isConnected() : false;
     }
 
+    _enableRefreshSession() {
+        if (this.authSession) return;
+        this.options.sessionMode = 'refresh';
+        this.authSession = AuthSession.forServer(this.options.serverUrl);
+        this.authSession.attach(this);
+        this.apiClient.authProvider = this.authSession;
+        this._authUnsubscribe = this.authSession.on('authStateChanged', event => this.emit('authStateChanged', event));
+        this._authErrorUnsubscribe = this.authSession.on('authError', error => this.emit('authError', error));
+        if (!this.authSession.data && this.options.jwtToken && tokenClaims(this.options.jwtToken).sid) {
+            this.authSession.data = { accessToken: this.options.jwtToken, projectId: this.options.projectId,
+                clientKey: this.options.apiKey, user: { userId: this.userId } };
+            this.authSession._setState('authenticated');
+        }
+        this._authReady = Promise.resolve();
+        if (this.authSession.data) this._authReady = this._acceptAuthSession(this.authSession.data).catch(error => {
+            this._authReady = Promise.resolve();
+            throw error;
+        });
+    }
+
+    async _acceptAuthSession(data) {
+        if (this.options.projectId && this.options.projectId !== data.projectId && this.connectionManager) {
+            await this._clearAuthSession();
+        }
+        this.options.apiKey = data.clientKey;
+        this.options.projectId = data.projectId;
+        this.apiClient.apiKey = data.clientKey;
+        this.apiClient.projectId = data.projectId;
+        await this.setToken(data.accessToken);
+    }
+
+    async _clearAuthSession() {
+        this._authConnectionRequested = false;
+        this.options.jwtToken = null;
+        this._userId = null;
+        this.apiClient.setJwtToken(null);
+        await this.disconnect();
+        this._chat?.destroy();
+        this._webrtc?.destroy();
+        await this.connectionManager?.destroy();
+        this._chat = null;
+        this._webrtc = null;
+        this.connectionManager = null;
+        this.pushManager?.reset();
+        this._pushManager = null;
+        this._pushEnablePromise = null;
+        this.emit('loggedOut');
+    }
+
+    getAuthState() {
+        return this.authSession?.getAuthState()
+            || (Number(tokenClaims(this.options.jwtToken || '').exp || 0) * 1000 > Date.now() ? 'authenticated' : 'unauthenticated');
+    }
+    isLoggedIn() { return this.getAuthState() === 'authenticated'; }
+    async getAccessToken(options = {}) {
+        if (this.authSession) { await this._authReady; return this.authSession.getAccessToken(options); }
+        if (!this.isLoggedIn()) { const error = new Error('Sign in is required'); error.code = 'SESSION_REVOKED'; throw error; }
+        return this.options.jwtToken;
+    }
+    async restoreSession() {
+        this._enableRefreshSession();
+        await this._authReady;
+        return this.authSession.restoreSession();
+    }
+    static async restoreSession({ serverUrl }) {
+        if (!serverUrl) throw new Error('serverUrl is required');
+        return AuthSession.forServer(serverUrl).restoreSession();
+    }
+
+    /** FE의 관리/캘린더 직접 호출도 동일한 인증·1회 재시도 경로를 사용한다. */
+    async request(method, path, options = {}) {
+        if (!path.startsWith('/') || path.startsWith('//')) throw new Error('Use an API-relative path');
+        await this._authReady;
+        return this.apiClient.request(method, path, options);
+    }
+
     /**
      * 현재 연결 상태
      * @returns {string}
@@ -257,9 +338,7 @@ class TalkFlowClient extends EventEmitter {
         if (!password) throw new Error('password is required');
 
         // 로그인은 키를 «받기 위해» 부르는 경로라 X-API-KEY/X-PROJECT-ID 가 없다(서버에서 필터 제외).
-        const client = new ApiClient({ baseUrl: serverUrl, apiKey: '', projectId: '' });
-        const response = await client.post('/api/v1/auth/login', { email, password });
-        return (response && response.data) ? response.data : response;
+        return AuthSession.forServer(serverUrl).login({ email, password });
     }
 
     /**
@@ -274,14 +353,10 @@ class TalkFlowClient extends EventEmitter {
      * @returns {Promise<Object>} 로그인 응답
      */
     async loginUser({ email, password }) {
-        const response = await this.apiClient.post('/api/v1/auth/login', { email, password });
-        const data = (response && response.data) ? response.data : response;
-
-        if (data && data.accessToken) {
-            await this.setToken(data.accessToken);
-            this.logger.info('Member logged in, token auto-set');
-        }
-        return data;
+        if (!email || !password) throw new Error('email and password are required');
+        this._enableRefreshSession();
+        await this._authReady;
+        return this.authSession.login({ email, password });
     }
 
     /**
@@ -354,7 +429,7 @@ class TalkFlowClient extends EventEmitter {
      * 비밀번호 변경 — 현재 비밀번호를 재확인한다.
      *
      * <p>토큰만 탈취해도 비밀번호를 바꿀 수 있으면 계정을 통째로 빼앗긴다. 비밀번호는 바뀌어도
-     * 토큰은 그대로 유효하다 — 재로그인이 필요하지 않다.</p>
+     * 현재 클라이언트는 새 세션을 받아 유지하고, 다른 세션은 종료한다.</p>
      *
      * @param {Object} params
      * @param {string} params.currentPassword
@@ -362,7 +437,19 @@ class TalkFlowClient extends EventEmitter {
      */
     async changeMyPassword({ currentPassword, newPassword }) {
         this._checkToken();
-        return this.apiClient.put('/api/v1/me/password', { currentPassword, newPassword });
+        if (this.authSession) {
+            return this.authSession.changePassword(() => this.apiClient.request('PUT', '/api/v1/me/password', {
+                body: { currentPassword, newPassword }, skipAuth: true
+            }));
+        }
+        const response = await this.apiClient.put('/api/v1/me/password', { currentPassword, newPassword });
+        const data = response?.data ?? response;
+        if (data?.accessToken && data?.refreshToken) {
+            this._enableRefreshSession();
+            this.authSession._newMarker(false);
+            await this.authSession._accept(data);
+        }
+        return response;
     }
 
     /**
@@ -586,6 +673,9 @@ class TalkFlowClient extends EventEmitter {
      */
     async destroy() {
         await this.disconnect();
+        this._authUnsubscribe?.();
+        this._authErrorUnsubscribe?.();
+        this.authSession?.detach(this);
 
         if (this.chat) {
             this.chat.destroy();

package/src/auth/AuthSession.js

@@ -0,0 +1,409 @@
+import EventEmitter from '../utils/EventEmitter.js';
+
+const sessions = new Map();
+const TERMINAL_CODES = new Set(['REFRESH_INVALID', 'REFRESH_REUSED', 'SESSION_REVOKED', 'ACCOUNT_BLOCKED', 'LOGIN_FAILED']);
+export const isTerminalAuthError = error => TERMINAL_CODES.has(error?.response?.code || error?.code);
+
+export function tokenClaims(token) {
+    try {
+        const value = token.replace(/^Bearer\s+/i, '').split('.')[1].replace(/-/g, '+').replace(/_/g, '/');
+        return JSON.parse(atob(value));
+    } catch { return {}; }
+}
+
+/** 서버별 인증 상태. Access는 메모리, Refresh와 로그아웃 의도는 하나의 저장 레코드로 관리한다. */
+export default class AuthSession extends EventEmitter {
+    static forServer(serverUrl) {
+        const url = serverUrl.replace(/\/$/, '');
+        if (!sessions.has(url)) sessions.set(url, new AuthSession(url));
+        return sessions.get(url);
+    }
+
+    constructor(serverUrl) {
+        super();
+        this.serverUrl = serverUrl;
+        this.state = 'checking';
+        this.data = null;
+        this.clients = new Set();
+        this.generation = 0;
+        this.refreshPromise = null;
+        this.timer = null;
+        this.peerWaiters = new Map();
+        this.markerKey = `talkflow:auth:${serverUrl}`;
+        this.marker = this._readMarker();
+        this.serverClock = null;
+        this.channel = null;
+        this.storageListener = event => {
+            if (event.key !== this.markerKey) return;
+            const stored = this._readMarker();
+            if (stored.revision !== this.marker.revision || stored.logout) {
+                this.marker = stored;
+                this.generation++;
+                this._clear(false).catch(error => this.emit('authError', error));
+            }
+        };
+        globalThis.addEventListener?.('storage', this.storageListener);
+        if (typeof window !== 'undefined' && typeof BroadcastChannel !== 'undefined') {
+            this.channel = new BroadcastChannel(`talkflow:auth:${serverUrl}`);
+            this.channel.onmessage = event => this._receive(event.data);
+            this.channel.unref?.();
+        }
+    }
+
+    _readMarker() {
+        try {
+            const value = globalThis.localStorage?.getItem(this.markerKey);
+            return value ? JSON.parse(value) : { revision: 'initial', logout: false };
+        } catch { throw this._storageError(); }
+    }
+    _storageError() { const error = new Error('Authentication storage is unavailable'); error.code = 'AUTH_STORAGE_UNAVAILABLE'; return error; }
+    _writeMarker(marker) {
+        try {
+            if (!globalThis.localStorage) throw this._storageError();
+            globalThis.localStorage.setItem(this.markerKey, JSON.stringify(marker));
+            this.marker = marker;
+        } catch { throw this._storageError(); }
+    }
+    _newMarker(logout, pending = logout) {
+        const previous = this._readMarker();
+        const marker = { revision: globalThis.crypto?.randomUUID?.() || String(Date.now()) + '-' + Math.random(), logout,
+            deviceId: previous.deviceId, pending,
+            pendingRefreshToken: logout && pending ? previous.refreshToken || previous.pendingRefreshToken : undefined };
+        this._writeMarker(marker);
+        return marker;
+    }
+    setDeviceId(deviceId) { this._writeMarker({ ...this._readMarker(), deviceId }); }
+    _monotonic() { return globalThis.performance?.now?.() ?? Date.now(); }
+    _serverNow() {
+        if (!this.serverClock) return Date.now();
+        return this.serverClock.server + Math.max(this._monotonic() - this.serverClock.mono, Date.now() - this.serverClock.wall);
+    }
+    _shareData() { return this.data ? { ...this.data, refreshToken: undefined, serverTime: this._serverNow() } : null; }
+    _publish(type, data, marker = this.marker) {
+        const { revision, logout, pending } = marker;
+        this.channel?.postMessage({ type, marker: { revision, logout, pending }, data });
+    }
+    _setState(state, error, force = false) {
+        const previous = this.state;
+        this.state = state;
+        if (previous !== state || error || force) this.emit('authStateChanged', { state, previous, error });
+    }
+    getAuthState() { return this.state; }
+    isLoggedIn() { return this.state === 'authenticated'; }
+    _fresh(token = this.data?.accessToken) { return Number(tokenClaims(token || '').exp || 0) * 1000 > this._serverNow() + (this.refreshMargin ?? 60000); }
+
+    attach(client) { this.clients.add(client); }
+    detach(client) { this.clients.delete(client); this.schedule(); }
+
+    _enqueue(work) {
+        const operation = (this.transition || Promise.resolve()).then(work);
+        this.transition = operation.catch(() => {});
+        return operation;
+    }
+
+    _accept(data, publish = true) {
+        const generation = this.generation;
+        const marker = this.marker;
+        return this._enqueue(async () => {
+            if (generation !== this.generation) throw this._cancelled();
+            if (!data?.accessToken || !data?.projectId || !data?.clientKey || !data?.user?.userId) {
+                const error = new Error('Invalid authentication response'); error.code = 'AUTH_UNAVAILABLE'; throw error;
+            }
+            const identityChanged = this.data && (this.data.user.userId !== data.user.userId || this.data.projectId !== data.projectId);
+            if (publish && data.refreshToken) {
+                const stored = this._readMarker();
+                if (stored.revision !== marker.revision || stored.logout) throw this._cancelled();
+                this._writeMarker({ ...stored, refreshToken: data.refreshToken, refreshRequestId: undefined, pending: false, pendingRefreshToken: undefined });
+            }
+            if (Number.isFinite(data.serverTime)) this.serverClock = {
+                server: data.serverTime + (data._roundTripMillis || 0), mono: this._monotonic(), wall: Date.now()
+            };
+            this.refreshMargin = Math.min(60000, Math.max(0, Number(tokenClaims(data.accessToken).exp) * 1000 - this._serverNow()) / 10);
+            // Access 응답만 메모리에 남긴다. Refresh는 매 갱신 시 저장소에서 다시 읽는다.
+            this.data = { ...data, refreshToken: undefined };
+            await Promise.all([...this.clients].map(client => client._acceptAuthSession(data)));
+            if (generation !== this.generation) throw this._cancelled();
+            this._setState('authenticated', undefined, identityChanged);
+            if (publish) this._publish('tokens', this._shareData(), this.marker);
+            this._reconnectClients();
+            this.schedule();
+            return data;
+        });
+    }
+
+    _reconnectClients() {
+        for (const client of this.clients) {
+            if (client._authConnectionRequested && client.isConnected?.()) {
+                const manager = client.connectionManager;
+                if (manager?._authenticatedToken !== this.data?.accessToken) {
+                    manager.forceReconnect('access-token-renewed').catch(error => this.emit('authError', error));
+                }
+            }
+        }
+    }
+
+    _clear(publish = true) {
+        const marker = this.marker;
+        return this._enqueue(async () => {
+            this.data = null;
+            clearTimeout(this.timer);
+            this.timer = null;
+            this._setState('unauthenticated');
+            await Promise.all([...this.clients].map(client => client._clearAuthSession()));
+            if (publish) this._publish('logout', undefined, marker);
+        });
+    }
+
+    async _receive(message) {
+        if (!message?.marker) return;
+        try {
+            const stored = this._readMarker();
+            if (message.marker.revision !== stored.revision && stored.revision !== this.marker.revision) return;
+            if (message.type === 'logout' || message.type === 'login-start') {
+                if (message.marker.revision !== stored.revision) return;
+                this.marker = message.marker;
+                this.generation++;
+                await this._clear(false);
+                if (message.type === 'login-start') this._setState('checking');
+                return;
+            }
+            if (message.marker.revision !== this._readMarker().revision || message.marker.logout) return;
+            if (message.type === 'request-token' && this._fresh()) {
+                this._publish('peer-token', { requestId: message.data.requestId, session: this._shareData() });
+            } else if (message.type === 'peer-token') {
+                this.peerWaiters.get(message.data.requestId)?.(message.data.session);
+            } else if (message.type === 'tokens') {
+                if (this.marker.revision !== message.marker.revision) this.generation++;
+                this.marker = message.marker;
+                // 지연된 방송이 더 최근 토큰을 덮어쓰지 않도록 한다.
+                const incoming = tokenClaims(message.data?.accessToken || '');
+                const current = tokenClaims(this.data?.accessToken || '');
+                if (incoming.sid === current.sid && incoming.exp < current.exp) return;
+                await this._accept(message.data, false);
+            }
+        } catch (error) { this.emit('authError', error); }
+    }
+
+    async _peerToken(rejectedToken) {
+        if (!this.channel) return null;
+        const requestId = `${Date.now()}-${Math.random()}`;
+        return new Promise(resolve => {
+            const done = data => {
+                if (data && (data.accessToken === rejectedToken || Number(tokenClaims(data.accessToken).exp) * 1000 <= Number(data.serverTime) + 60000)) return;
+                clearTimeout(timer);
+                this.peerWaiters.delete(requestId);
+                resolve(data);
+            };
+            const timer = setTimeout(() => done(null), 100);
+            this.peerWaiters.set(requestId, done);
+            this._publish('request-token', { requestId });
+        });
+    }
+
+    _locked(work) {
+        const locks = typeof navigator !== 'undefined' ? navigator.locks : null;
+        const operation = (this.httpQueue || Promise.resolve()).then(() =>
+            locks?.request ? locks.request(`talkflow:auth:${this.serverUrl}`, work) : work());
+        this.httpQueue = operation.catch(() => {});
+        return operation;
+    }
+
+    _newRefreshRequestId() {
+        const bytes = new Uint8Array(32);
+        if (!globalThis.crypto?.getRandomValues) {
+            const error = new Error('Secure randomness is unavailable'); error.code = 'AUTH_RANDOM_UNAVAILABLE'; throw error;
+        }
+        globalThis.crypto.getRandomValues(bytes);
+        return Array.from(bytes, byte => byte.toString(16).padStart(2, '0')).join('');
+    }
+
+    async _request(path, body, headers = {}) {
+        const started = this._monotonic();
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 15000);
+        try {
+            const response = await fetch(`${this.serverUrl}${path}`, {
+                method: 'POST', credentials: 'omit', signal: controller.signal,
+                headers: { 'Content-Type': 'application/json', 'X-TalkFlow-Session': 'refresh', ...headers },
+                body: body === undefined ? undefined : JSON.stringify(body)
+            });
+            const text = response.headers.get('content-type')?.includes('application/json')
+                ? await response.json() : await response.text();
+            if (!response.ok) {
+                const error = new Error(text?.message || `HTTP ${response.status}`);
+                error.status = response.status; error.code = text?.code; error.response = text;
+                throw error;
+            }
+            const data = text?.data !== undefined ? text.data : text;
+            if (data && typeof data === 'object') return Object.defineProperty({ ...data }, '_roundTripMillis', { value: this._monotonic() - started });
+            return data;
+        } finally { clearTimeout(timeout); }
+    }
+
+    async login({ email, password }) {
+        const generation = ++this.generation;
+        return this._locked(async () => {
+            const previous = this._readMarker();
+            this._writeMarker(previous);
+            if (previous.pendingRefreshToken) await this._request('/v1/auth/signout', { refreshToken: previous.pendingRefreshToken, deviceId: previous.deviceId });
+            const data = await this._request('/api/v1/auth/login', { email, password, previousRefreshToken: previous.refreshToken });
+            if (!data?.refreshToken) {
+                const error = new Error('Server does not support the refresh session contract');
+                error.code = 'AUTH_PROTOCOL_UNSUPPORTED';
+                throw error;
+            }
+            if (generation !== this.generation || this._readMarker().revision !== previous.revision) {
+                await this._request('/v1/auth/signout', { refreshToken: data.refreshToken });
+                throw this._cancelled();
+            }
+            this._newMarker(false);
+            return this._accept(data);
+        });
+    }
+
+    async restoreSession() {
+        if (this._readMarker().logout) {
+            if (this._readMarker().pending) await this.logout();
+            else await this._clear(false);
+            return null;
+        }
+        if (this._fresh()) return this.data;
+        if (!this._readMarker().refreshToken) { await this._clear(false); return null; }
+        if (!this.data) this._setState('checking');
+        try { await this.getAccessToken(); return this.data; }
+        catch (error) { if (isTerminalAuthError(error)) return null; throw error; }
+    }
+
+    async getAccessToken({ forceRefresh = false, rejectedToken } = {}) {
+        if (this._readMarker().logout) throw this._loggedOut();
+        if (this._fresh() && (!forceRefresh || (rejectedToken && rejectedToken !== this.data.accessToken)))
+            return this.data.accessToken;
+        if (this.refreshPromise) return this.refreshPromise;
+        const generation = this.generation;
+        const revision = this._readMarker().revision;
+        const operation = this._locked(async () => {
+            if (generation !== this.generation || revision !== this._readMarker().revision) throw this._cancelled();
+            if (this._fresh() && (!forceRefresh || (rejectedToken && rejectedToken !== this.data.accessToken)))
+                return this.data.accessToken;
+            this.marker = this._readMarker();
+            if (!this.marker.refreshToken) throw this._loggedOut();
+            // 회전 전에 저장 가능 여부를 확인한다. 잠금 대기 전 읽은 토큰은 사용하지 않는다.
+            this._writeMarker(this.marker);
+            const peer = await this._peerToken(rejectedToken);
+            let data = peer;
+            if (!data) {
+                // 요청 전에 자격과 식별자를 함께 저장한다. 실패·재시작 뒤에도 같은 요청으로 복구한다.
+                const stored = this._readMarker();
+                if (generation !== this.generation || revision !== stored.revision || stored.logout) throw this._cancelled();
+                const requestId = stored.refreshRequestId || this._newRefreshRequestId();
+                this._writeMarker({ ...stored, refreshRequestId: requestId });
+                data = await this._request('/api/v1/auth/refresh', { refreshToken: stored.refreshToken, requestId });
+            }
+            if (generation !== this.generation || revision !== this._readMarker().revision) throw this._cancelled();
+            await this._accept(data, !peer);
+            return data.accessToken;
+        }).catch(async error => {
+            if (generation === this.generation && revision === this._readMarker().revision) {
+                if (isTerminalAuthError(error)) await this.authenticationFailed(error);
+                else if (!this.data) this._setState('unavailable', error);
+                else this.emit('authError', error);
+            }
+            throw error;
+        }).finally(() => { if (this.refreshPromise === operation) this.refreshPromise = null; });
+        this.refreshPromise = operation;
+        return operation;
+    }
+
+    async logout() {
+        const token = this.data?.accessToken;
+        this.generation++;
+        const marker = this._newMarker(true);
+        // 로컬 정리보다 먼저 HTTP 순서를 예약해 뒤의 로그인이 로그아웃을 추월하지 못하게 한다.
+        const cleanup = this._clear();
+        const request = this._locked(async () => {
+            const result = await this._request('/v1/auth/signout', { refreshToken: marker.pendingRefreshToken, deviceId: marker.deviceId },
+                token ? { Authorization: 'Bearer ' + token.replace(/^Bearer\s+/i, '') } : {});
+            if (this._readMarker().revision === marker.revision) this._writeMarker({ ...marker, pending: false, pendingRefreshToken: undefined });
+            return result;
+        });
+        await Promise.all([cleanup, request]);
+        if (this._readMarker().revision === marker.revision) {
+            this._writeMarker({ ...marker, pending: false, pendingRefreshToken: undefined });
+        }
+        // 명시적 로그인 전에는 재시작해도 로그아웃 의도를 유지한다.
+    }
+
+    async changePassword(request) {
+        await this.getAccessToken();
+        const generation = ++this.generation;
+        return this._locked(async () => {
+            const response = await request();
+            if (generation !== this.generation) throw this._cancelled();
+            const data = response?.data ?? response;
+            if (data?.reauthenticationRequired) {
+                this._newMarker(true, false);
+                await this._clear();
+                return response;
+            }
+            this._newMarker(false);
+            await this._accept(data);
+            return response;
+        }).catch(async error => {
+            if (generation === this.generation) await this.authenticationFailed(error);
+            throw error;
+        });
+    }
+
+    _loggedOut() { const error = new Error('Sign in is required'); error.code = 'SESSION_REVOKED'; return error; }
+    async authenticationFailed(error, { rejectedToken, generation } = {}) {
+        if (generation !== undefined && generation !== this.generation) return;
+        if (rejectedToken && this.data && rejectedToken !== this.data.accessToken) return;
+        if (isTerminalAuthError(error)) {
+            this.generation++;
+            this._newMarker(true, false);
+            await this._clear();
+        }
+    }
+    replaceAccessToken(accessToken) {
+        if (!this.data || this.data.accessToken === accessToken) return;
+        const claims = tokenClaims(accessToken);
+        if (claims.sid !== tokenClaims(this.data.accessToken).sid || claims.sub !== this.data.user.userId) return;
+        this.data = { ...this.data, accessToken, expiresIn: claims.exp };
+        this._publish('tokens', this._shareData());
+        this._reconnectClients();
+        this.schedule();
+    }
+    _cancelled() { const error = new Error('Authentication operation was superseded'); error.code = 'AUTH_OPERATION_CANCELLED'; return error; }
+
+    schedule(delay) {
+        clearTimeout(this.timer);
+        this.timer = null;
+        if (!this.data || ![...this.clients].some(client => client._authConnectionRequested)) return;
+        const wait = delay ?? Math.max(1000, Number(tokenClaims(this.data.accessToken).exp || 0) * 1000 - this._serverNow() - (this.refreshMargin ?? 60000));
+        this.timer = setTimeout(async () => {
+            try {
+                const before = this.data?.accessToken;
+                await this.getAccessToken({ forceRefresh: true, rejectedToken: before });
+                if (this.data) {
+                    await Promise.all([...this.clients].filter(client => client._authConnectionRequested
+                        && !client.isConnected())
+                        .map(client => client.connectionManager.forceReconnect('access-token-renewed')));
+                }
+                this.schedule();
+            } catch (error) {
+                if (!isTerminalAuthError(error)) this.schedule(30000);
+            }
+        }, wait);
+        this.timer.unref?.();
+    }
+
+    destroy() {
+        this.generation++;
+        clearTimeout(this.timer);
+        this.channel?.close();
+        globalThis.removeEventListener?.('storage', this.storageListener);
+        this.clients.clear();
+        this.removeAllListeners();
+        if (sessions.get(this.serverUrl) === this) sessions.delete(this.serverUrl);
+    }
+}