@lemoncloud/chatic-sockets-lib 0.3.4 → 0.4.1

package/dist/client-socket-v2/auth-controller.d.ts

@@ -0,0 +1,111 @@
+import type { AuthUpdateState, AuthTokenView } from '../lib/auth/contracts';
+import type { ClientSocketV2, SharedTimerScheduler } from './types';
+/** Auth state surfaced to the app: server states plus the client-terminal 'expired'. */
+export declare type AuthControllerState = AuthUpdateState | 'expired';
+/** App-provided signing callback (stateless); the SDK injects the current token, the app returns the lemon hmac signature. */
+export declare type AuthSignCallback = (token: string, ctx?: {
+    target?: string;
+}) => Promise<{
+    signature: string;
+    current: string;
+}>;
+/** Registration input for `register()`. */
+export interface AuthRegisterOptions {
+    token: string;
+    authId: string;
+    sign: AuthSignCallback;
+}
+/** Per-call switch hooks. */
+export interface AuthSwitchHandlers {
+    onSuccess?(res: AuthTokenView): void;
+    onError?(err: AuthSwitchError): void;
+}
+/** Typed error capturing the switch failure phase. */
+export declare class AuthSwitchError extends Error {
+    readonly phase: 'not-connected' | 'sign' | 'server';
+    readonly cause?: unknown;
+    readonly serverResponse?: AuthTokenView;
+    constructor(opts: {
+        phase: AuthSwitchError['phase'];
+        cause?: unknown;
+        serverResponse?: AuthTokenView;
+    });
+}
+export interface AuthControllerOptionsPartial {
+    refreshIntervalMs?: number;
+    minBackoffMs?: number;
+    maxBackoffMs?: number;
+    backoffFactor?: number;
+    maxFailures?: number;
+    validatingTimeoutMs?: number;
+    now?: () => number;
+}
+export interface AuthControllerOptions extends AuthControllerOptionsPartial {
+    client: ClientSocketV2;
+    timerScheduler?: SharedTimerScheduler;
+}
+export interface AuthController {
+    readonly state: AuthControllerState;
+    /** Current token, for the app's HTTP Authorization header. */
+    readonly token: string;
+    register(opts: AuthRegisterOptions): void;
+    /** Resolves once authenticated (immediately if already); rejects if auth expires. */
+    ready(): Promise<void>;
+    switch(target: string, handlers?: AuthSwitchHandlers): Promise<AuthTokenView>;
+    /** Clear local auth state and stop the scheduler. */
+    logout(): Promise<void>;
+    onAuthState(listener: (state: AuthControllerState) => void): () => void;
+    /** Fires on every refresh/switch success (including SDK periodic refresh) with the full payload. */
+    onTokenRefresh(listener: (view: AuthTokenView) => void): () => void;
+}
+export declare class AuthControllerImpl implements AuthController {
+    private readonly options;
+    private readonly refreshIntervalMs;
+    private readonly minBackoffMs;
+    private readonly maxBackoffMs;
+    private readonly backoffFactor;
+    private readonly maxFailures;
+    private readonly validatingTimeoutMs;
+    private readonly now;
+    private readonly timerScheduler?;
+    private readonly gateway;
+    private readonly unsubs;
+    private readonly stateListeners;
+    private readonly tokenListeners;
+    private _state;
+    private epoch;
+    private failures;
+    private _token;
+    private authId;
+    private signCallback?;
+    private active;
+    constructor(options: AuthControllerOptions);
+    get state(): AuthControllerState;
+    get token(): string;
+    /** Register token, authId, and sign callback. Idempotent; resumes auth when inactive (after logout or expiry). */
+    register: (opts: AuthRegisterOptions) => void;
+    /** Resolves once authenticated (immediately if already); rejects if auth expires. */
+    ready: () => Promise<void>;
+    /** Switch to another site. */
+    switch: (target: string, handlers?: AuthSwitchHandlers) => Promise<AuthTokenView>;
+    /** Clear local auth state and stop the scheduler. Best-effort server notify (revokes the backend session). */
+    logout: () => Promise<void>;
+    onAuthState: (listener: (state: AuthControllerState) => void) => (() => void);
+    onTokenRefresh: (listener: (view: AuthTokenView) => void) => (() => void);
+    private emitToken;
+    start: () => void;
+    stop: () => void;
+    destroy: () => void;
+    private sendUpdate;
+    private runRefresh;
+    private handleAuthResponse;
+    private handleFailed;
+    private runReauth;
+    private computeBackoffDelay;
+    private scheduleRefresh;
+    private rearmRefreshTimer;
+    private schedule;
+    private clearTimer;
+    private clearTimers;
+    private setState;
+}

package/dist/client-socket-v2/auth-controller.js

@@ -0,0 +1,344 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthControllerImpl = exports.AuthSwitchError = void 0;
+const auth_gateway_1 = require("./gateways/auth-gateway");
+/** Typed error capturing the switch failure phase. */
+class AuthSwitchError extends Error {
+    constructor(opts) {
+        super(`auth.switch failed: ${opts.phase}`);
+        this.phase = opts.phase;
+        this.cause = opts.cause;
+        this.serverResponse = opts.serverResponse;
+    }
+}
+exports.AuthSwitchError = AuthSwitchError;
+class AuthControllerImpl {
+    constructor(options) {
+        var _a, _b, _c, _d, _e, _f, _g;
+        this.options = options;
+        this.unsubs = [];
+        this.stateListeners = new Set();
+        this.tokenListeners = new Set();
+        this._state = '';
+        this.epoch = 0;
+        this.failures = 0;
+        this._token = '';
+        this.authId = '';
+        this.active = false;
+        /** Register token, authId, and sign callback. Idempotent; resumes auth when inactive (after logout or expiry). */
+        this.register = (opts) => {
+            this._token = opts.token;
+            this.authId = opts.authId;
+            this.signCallback = opts.sign;
+            if (!this.active) {
+                this.failures = 0;
+                this.active = true;
+                this.setState('pending');
+                if (this.options.client.state === 'connected') {
+                    this.epoch++;
+                    void this.sendUpdate();
+                }
+            }
+        };
+        /** Resolves once authenticated (immediately if already); rejects if auth expires. */
+        this.ready = () => {
+            if (this._state === 'authenticated')
+                return Promise.resolve();
+            return new Promise((resolve, reject) => {
+                const off = this.onAuthState(s => {
+                    if (s === 'authenticated') {
+                        off();
+                        resolve();
+                    }
+                    else if (s === 'expired' || s === '') {
+                        off();
+                        reject(new Error(`401 UNAUTHORIZED - auth ${s === 'expired' ? 'expired' : 'logged out'}`));
+                    }
+                });
+            });
+        };
+        /** Switch to another site. */
+        this.switch = (target, handlers) => __awaiter(this, void 0, void 0, function* () {
+            var _h, _j, _k, _l, _m, _o, _p, _q;
+            if (this.options.client.state !== 'connected') {
+                const err = new AuthSwitchError({ phase: 'not-connected' });
+                (_h = handlers === null || handlers === void 0 ? void 0 : handlers.onError) === null || _h === void 0 ? void 0 : _h.call(handlers, err);
+                throw err;
+            }
+            this.epoch++;
+            const myEpoch = this.epoch;
+            /** suspend periodic refresh to avoid an epoch race with switch */
+            this.clearTimer('auth:refresh');
+            let signResult;
+            try {
+                signResult = (_k = (yield ((_j = this.signCallback) === null || _j === void 0 ? void 0 : _j.call(this, this._token, { target })))) !== null && _k !== void 0 ? _k : { signature: '', current: '' };
+            }
+            catch (cause) {
+                const err = new AuthSwitchError({ phase: 'sign', cause });
+                (_l = handlers === null || handlers === void 0 ? void 0 : handlers.onError) === null || _l === void 0 ? void 0 : _l.call(handlers, err);
+                this.rearmRefreshTimer();
+                throw err;
+            }
+            try {
+                const res = yield this.gateway.switch({
+                    current: signResult.current,
+                    signature: signResult.signature,
+                    authId: this.authId,
+                    target,
+                });
+                const view = res;
+                if (myEpoch !== this.epoch)
+                    return view;
+                this._token = (_o = (_m = view === null || view === void 0 ? void 0 : view.Token) === null || _m === void 0 ? void 0 : _m.identityToken) !== null && _o !== void 0 ? _o : this._token;
+                this.setState('authenticated');
+                this.emitToken(view);
+                (_p = handlers === null || handlers === void 0 ? void 0 : handlers.onSuccess) === null || _p === void 0 ? void 0 : _p.call(handlers, view);
+                return view;
+            }
+            catch (e) {
+                if (e instanceof AuthSwitchError)
+                    throw e;
+                const err = new AuthSwitchError({ phase: 'server', cause: e });
+                (_q = handlers === null || handlers === void 0 ? void 0 : handlers.onError) === null || _q === void 0 ? void 0 : _q.call(handlers, err);
+                throw err;
+            }
+            finally {
+                this.rearmRefreshTimer();
+            }
+        });
+        /** Clear local auth state and stop the scheduler. Best-effort server notify (revokes the backend session). */
+        this.logout = () => __awaiter(this, void 0, void 0, function* () {
+            /** bump epoch so a late in-flight refresh/switch/reauth response can't resurrect auth after logout */
+            this.epoch++;
+            this.stop();
+            this._token = '';
+            this.authId = '';
+            this.signCallback = undefined;
+            this.setState('');
+            if (this.options.client.state === 'connected') {
+                yield this.gateway.logout({}).catch(() => undefined);
+            }
+        });
+        this.onAuthState = (listener) => {
+            this.stateListeners.add(listener);
+            return () => this.stateListeners.delete(listener);
+        };
+        this.onTokenRefresh = (listener) => {
+            this.tokenListeners.add(listener);
+            return () => this.tokenListeners.delete(listener);
+        };
+        this.emitToken = (view) => {
+            this.tokenListeners.forEach(l => l(view));
+        };
+        this.start = () => {
+            this.active = true;
+            if (this.options.client.state === 'connected' && this._token) {
+                this.epoch++;
+                void this.sendUpdate();
+            }
+        };
+        this.stop = () => {
+            this.active = false;
+            this.clearTimers();
+        };
+        this.destroy = () => {
+            this.stop();
+            this.unsubs.splice(0).forEach(unsub => unsub());
+            this.stateListeners.clear();
+            this.tokenListeners.clear();
+        };
+        this.sendUpdate = () => __awaiter(this, void 0, void 0, function* () {
+            var _r;
+            if (!this._token)
+                return;
+            const myEpoch = this.epoch;
+            this.setState('pending');
+            try {
+                const res = yield this.gateway.update({ token: this._token });
+                if (myEpoch !== this.epoch)
+                    return;
+                this.handleAuthResponse((_r = res === null || res === void 0 ? void 0 : res.state) !== null && _r !== void 0 ? _r : 'failed');
+            }
+            catch (_s) {
+                if (myEpoch !== this.epoch)
+                    return;
+                this.handleFailed();
+            }
+        });
+        this.runRefresh = () => __awaiter(this, void 0, void 0, function* () {
+            var _t, _u;
+            if (!this.signCallback)
+                return;
+            this.epoch++;
+            const myEpoch = this.epoch;
+            let signResult;
+            try {
+                signResult = yield this.signCallback(this._token);
+            }
+            catch (_v) {
+                if (myEpoch !== this.epoch)
+                    return;
+                this.handleFailed();
+                return;
+            }
+            try {
+                const res = yield this.gateway.refresh({
+                    current: signResult.current,
+                    signature: signResult.signature,
+                    authId: this.authId,
+                });
+                if (myEpoch !== this.epoch)
+                    return;
+                const view = res;
+                this._token = (_u = (_t = view === null || view === void 0 ? void 0 : view.Token) === null || _t === void 0 ? void 0 : _t.identityToken) !== null && _u !== void 0 ? _u : this._token;
+                this.failures = 0;
+                this.setState('authenticated');
+                this.scheduleRefresh();
+                this.emitToken(view);
+            }
+            catch (_w) {
+                if (myEpoch !== this.epoch)
+                    return;
+                this.handleFailed();
+            }
+        });
+        this.handleAuthResponse = (state) => {
+            if (state === 'authenticated') {
+                this.failures = 0;
+                this.setState('authenticated');
+                this.scheduleRefresh();
+            }
+            else if (state === 'validating') {
+                this.setState('validating');
+                this.schedule('auth:validating', this.validatingTimeoutMs, () => {
+                    if (this._state === 'validating')
+                        this.handleFailed();
+                });
+            }
+            else {
+                this.handleFailed();
+            }
+        };
+        this.handleFailed = () => {
+            this.failures++;
+            this.setState('failed');
+            this.clearTimer('auth:refresh');
+            this.clearTimer('auth:validating');
+            if (this.failures > this.maxFailures) {
+                this.setState('expired');
+                this.active = false;
+                return;
+            }
+            const delay = this.computeBackoffDelay(this.failures - 1);
+            this.schedule('auth:reauth', delay, () => void this.runReauth());
+        };
+        this.runReauth = () => __awaiter(this, void 0, void 0, function* () {
+            var _x, _y;
+            if (!this.signCallback)
+                return;
+            this.epoch++;
+            const myEpoch = this.epoch;
+            let signResult;
+            try {
+                signResult = yield this.signCallback(this._token);
+            }
+            catch (_z) {
+                if (myEpoch !== this.epoch)
+                    return;
+                this.handleFailed();
+                return;
+            }
+            try {
+                const res = yield this.gateway.refresh({
+                    current: signResult.current,
+                    signature: signResult.signature,
+                    authId: this.authId,
+                });
+                if (myEpoch !== this.epoch)
+                    return;
+                const view = res;
+                this._token = (_y = (_x = view === null || view === void 0 ? void 0 : view.Token) === null || _x === void 0 ? void 0 : _x.identityToken) !== null && _y !== void 0 ? _y : this._token;
+                this.failures = 0;
+                this.setState('authenticated');
+                this.scheduleRefresh();
+                this.emitToken(view);
+            }
+            catch (_0) {
+                if (myEpoch !== this.epoch)
+                    return;
+                this.handleFailed();
+            }
+        });
+        this.computeBackoffDelay = (attempt) => {
+            const expDelay = Math.min(this.minBackoffMs * Math.pow(this.backoffFactor, attempt), this.maxBackoffMs);
+            const jitter = expDelay * (Math.random() * 2 - 1) * 0.3;
+            return Math.max(this.minBackoffMs, Math.min(this.maxBackoffMs, expDelay + jitter));
+        };
+        this.scheduleRefresh = () => {
+            this.schedule('auth:refresh', this.refreshIntervalMs, () => void this.runRefresh());
+        };
+        this.rearmRefreshTimer = () => {
+            if (this._state === 'authenticated')
+                this.scheduleRefresh();
+        };
+        this.schedule = (key, delayMs, task) => {
+            if (this.timerScheduler) {
+                this.timerScheduler.schedule(key, delayMs, task);
+            }
+            else {
+                setTimeout(task, delayMs);
+            }
+        };
+        this.clearTimer = (key) => {
+            var _a;
+            (_a = this.timerScheduler) === null || _a === void 0 ? void 0 : _a.cancel(key);
+        };
+        this.clearTimers = () => {
+            this.clearTimer('auth:refresh');
+            this.clearTimer('auth:reauth');
+            this.clearTimer('auth:validating');
+        };
+        this.setState = (next) => {
+            if (this._state === next)
+                return;
+            this._state = next;
+            this.stateListeners.forEach(l => l(next));
+        };
+        this.refreshIntervalMs = (_a = options.refreshIntervalMs) !== null && _a !== void 0 ? _a : 1800000;
+        this.minBackoffMs = (_b = options.minBackoffMs) !== null && _b !== void 0 ? _b : 1000;
+        this.maxBackoffMs = (_c = options.maxBackoffMs) !== null && _c !== void 0 ? _c : 30000;
+        this.backoffFactor = (_d = options.backoffFactor) !== null && _d !== void 0 ? _d : 2;
+        this.maxFailures = (_e = options.maxFailures) !== null && _e !== void 0 ? _e : 5;
+        this.validatingTimeoutMs = (_f = options.validatingTimeoutMs) !== null && _f !== void 0 ? _f : 15000;
+        this.now = (_g = options.now) !== null && _g !== void 0 ? _g : (() => Date.now());
+        this.timerScheduler = options.timerScheduler;
+        this.gateway = (0, auth_gateway_1.createAuthGateway)(options.client);
+        this.unsubs.push(options.client.onState(event => {
+            if (!this.active)
+                return;
+            if (event.next === 'connected') {
+                this.epoch++;
+                void this.sendUpdate();
+            }
+            if (event.next === 'closed' || event.next === 'closing') {
+                this.clearTimers();
+            }
+        }));
+    }
+    get state() {
+        return this._state;
+    }
+    get token() {
+        return this._token;
+    }
+}
+exports.AuthControllerImpl = AuthControllerImpl;

package/dist/client-socket-v2/create-client-socket-v2.js

@@ -17,6 +17,7 @@ const pending_request_store_1 = require("./pending-request-store");
 const reconnect_controller_1 = require("./reconnect-controller");
 const shared_timer_scheduler_1 = require("./shared-timer-scheduler");
 const socket_transport_1 = require("./socket-transport");
+const auth_controller_1 = require("./auth-controller");
 const buildMid = () => `m-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
 const parseMessage = (raw) => {
     const text = `${raw !== null && raw !== void 0 ? raw : ''}`.trim();
@@ -136,10 +137,11 @@ class ClientSocketV2Impl {
         };
         this.onType = (type, listener) => this.router.onType(type, listener);
         this.destroy = () => {
-            var _a, _b;
-            /** 순서 invariant: reconnect.destroy → keepAlive.destroy → transport.disconnect (그 close 이벤트를 reconnect가 못 듣게 하기 위함) → 나머지 정리 */
+            var _a, _b, _c;
+            /** 순서 invariant: reconnect.destroy → keepAlive.destroy → auth.destroy → transport.disconnect (그 close 이벤트를 reconnect가 못 듣게 하기 위함) → 나머지 정리 */
             (_a = this.reconnect) === null || _a === void 0 ? void 0 : _a.destroy();
             (_b = this.keepAlive) === null || _b === void 0 ? void 0 : _b.destroy();
+            (_c = this.auth) === null || _c === void 0 ? void 0 : _c.destroy();
             void this.transport.disconnect().catch(() => undefined);
             this.transportUnsubs.splice(0).forEach(unsub => unsub());
             this.rejectQueuedRequests(new Error(`499 CLIENT CLOSED REQUEST - client destroyed`));
@@ -283,6 +285,11 @@ class ClientSocketV2Impl {
         if (options.reconnect !== false) {
             this.reconnect = new reconnect_controller_1.AutoReconnectController(Object.assign({ client: this, timerScheduler: this.timerScheduler }, (options.reconnect || {})));
         }
+        if (options.auth !== false) {
+            const auth = new auth_controller_1.AuthControllerImpl(Object.assign({ client: this, timerScheduler: this.timerScheduler }, (options.auth || {})));
+            this.auth = auth;
+            auth.start();
+        }
     }
     get state() {
         return this._state;

package/dist/client-socket-v2/gateways/auth-gateway.d.ts

@@ -1,6 +1,9 @@
-import type { AuthUpdateInput, AuthUpdateResponse } from '../../lib/auth/types';
+import type { AuthRefreshInput, AuthRefreshResponse, AuthSwitchInput, AuthSwitchResponse, AuthLogoutInput, AuthLogoutResponse, AuthUpdateInput, AuthUpdateResponse } from '../../lib/auth/types';
 import type { ClientSocketV2 } from '../types';
 export interface AuthGateway {
     update(data: AuthUpdateInput): Promise<AuthUpdateResponse>;
+    refresh(data: AuthRefreshInput): Promise<AuthRefreshResponse>;
+    switch(data: AuthSwitchInput): Promise<AuthSwitchResponse>;
+    logout(data?: AuthLogoutInput): Promise<AuthLogoutResponse>;
 }
 export declare const createAuthGateway: (client: ClientSocketV2) => AuthGateway;

package/dist/client-socket-v2/gateways/auth-gateway.js

@@ -6,6 +6,9 @@ const createAuthGateway = (client) => {
     const gateway = (0, create_domain_gateway_1.createDomainGateway)('auth', client);
     return {
         update: data => gateway.request('update', data),
+        refresh: data => gateway.request('refresh', data),
+        switch: data => gateway.request('switch', data),
+        logout: data => gateway.request('logout', data !== null && data !== void 0 ? data : {}),
     };
 };
 exports.createAuthGateway = createAuthGateway;

package/dist/client-socket-v2/index.d.ts

@@ -27,6 +27,7 @@ export * from './gateways/create-domain-gateway';
 export * from './gateways/device-gateway';
 export * from './gateways/channel-gateway';
 export * from './gateways/auth-gateway';
+export * from './auth-controller';
 export * from './gateways/chat-gateway';
 export * from './gateways/join-gateway';
 export * from './gateways/cloud-gateway';

package/dist/client-socket-v2/index.js

@@ -44,6 +44,7 @@ __exportStar(require("./gateways/create-domain-gateway"), exports);
 __exportStar(require("./gateways/device-gateway"), exports);
 __exportStar(require("./gateways/channel-gateway"), exports);
 __exportStar(require("./gateways/auth-gateway"), exports);
+__exportStar(require("./auth-controller"), exports);
 __exportStar(require("./gateways/chat-gateway"), exports);
 __exportStar(require("./gateways/join-gateway"), exports);
 __exportStar(require("./gateways/cloud-gateway"), exports);

package/dist/client-socket-v2/plans/channel-sync-plan.d.ts

@@ -24,6 +24,7 @@ export interface ChannelSyncPlanOptions<TView extends SyncableView = SyncableVie
 export declare class ChannelSyncPlan<TView extends SyncableView = SyncableView> implements DomainSyncPlan<ChannelSyncTarget> {
     private readonly options;
     readonly domain = "channel";
+    readonly requiresAuth = true;
     readonly idleBackoff: SyncBackoffOptions;
     constructor(options?: ChannelSyncPlanOptions<TView>);
     supports: (target: SyncTargetDescriptor) => target is ChannelSyncTarget;

package/dist/client-socket-v2/plans/channel-sync-plan.js

@@ -20,6 +20,7 @@ class ChannelSyncPlan {
         var _a;
         this.options = options;
         this.domain = 'channel';
+        this.requiresAuth = true;
         this.supports = (target) => (target === null || target === void 0 ? void 0 : target.type) === 'channel';
         this.getKey = (target) => { var _a; return `channel:${(_a = target === null || target === void 0 ? void 0 : target.id) !== null && _a !== void 0 ? _a : ''}`; };
         this.getIntervalMs = (target) => { var _a, _b; return (_b = (_a = target.intervalMs) !== null && _a !== void 0 ? _a : this.options.intervalMs) !== null && _b !== void 0 ? _b : 2000; };

package/dist/client-socket-v2/plans/chat-sync-plan.d.ts

@@ -41,6 +41,7 @@ export interface ChatSyncPlanOptions<TMessage extends ChatMessageLike = ChatMess
 export declare class ChatSyncPlan<TMessage extends ChatMessageLike = ChatMessageLike> implements DomainSyncPlan<ChatSyncTarget> {
     private readonly options;
     readonly domain = "chat";
+    readonly requiresAuth = true;
     readonly idleBackoff: SyncBackoffOptions;
     private readonly chains;
     constructor(options?: ChatSyncPlanOptions<TMessage>);

package/dist/client-socket-v2/plans/chat-sync-plan.js

@@ -22,6 +22,7 @@ class ChatSyncPlan {
         var _a;
         this.options = options;
         this.domain = 'chat';
+        this.requiresAuth = true;
         this.chains = new Map();
         this.supports = (target) => (target === null || target === void 0 ? void 0 : target.type) === 'chat';
         this.getKey = (target) => { var _a; return `chat:${(_a = target === null || target === void 0 ? void 0 : target.id) !== null && _a !== void 0 ? _a : ''}`; };

package/dist/client-socket-v2/plans/device-sync-plan.d.ts

@@ -21,6 +21,7 @@ export interface DeviceSyncPlanOptions {
 export declare class DeviceSyncPlan implements DomainSyncPlan<DeviceSyncTarget> {
     private readonly options;
     readonly domain = "device";
+    readonly requiresAuth = false;
     readonly failurePolicy: SyncFailurePolicy;
     readonly idleBackoff: SyncBackoffOptions;
     constructor(options?: DeviceSyncPlanOptions);

package/dist/client-socket-v2/plans/device-sync-plan.js

@@ -15,6 +15,7 @@ class DeviceSyncPlan {
         var _a, _b;
         this.options = options;
         this.domain = 'device';
+        this.requiresAuth = false;
         this.supports = (target) => (target === null || target === void 0 ? void 0 : target.type) === 'device';
         this.getKey = (target) => { var _a; return `device:${(_a = target === null || target === void 0 ? void 0 : target.id) !== null && _a !== void 0 ? _a : 'current'}`; };
         this.getIntervalMs = (target) => { var _a, _b; return (_b = (_a = target.intervalMs) !== null && _a !== void 0 ? _a : this.options.intervalMs) !== null && _b !== void 0 ? _b : 2000; };

package/dist/client-socket-v2/plans/join-sync-plan.d.ts

@@ -24,6 +24,7 @@ export interface JoinSyncPlanOptions<TView extends SyncableView = SyncableView>
 export declare class JoinSyncPlan<TView extends SyncableView = SyncableView> implements DomainSyncPlan<JoinSyncTarget> {
     private readonly options;
     readonly domain = "join";
+    readonly requiresAuth = true;
     readonly idleBackoff: SyncBackoffOptions;
     constructor(options?: JoinSyncPlanOptions<TView>);
     supports: (target: SyncTargetDescriptor) => target is JoinSyncTarget;

package/dist/client-socket-v2/plans/join-sync-plan.js

@@ -20,6 +20,7 @@ class JoinSyncPlan {
         var _a;
         this.options = options;
         this.domain = 'join';
+        this.requiresAuth = true;
         this.supports = (target) => (target === null || target === void 0 ? void 0 : target.type) === 'join';
         this.getKey = (target) => { var _a; return `join:${(_a = target === null || target === void 0 ? void 0 : target.id) !== null && _a !== void 0 ? _a : ''}`; };
         // Default poll interval (10s); the scheduler backs this off x2 up to 60s while idle.

package/dist/client-socket-v2/plans/place-sync-plan.d.ts

@@ -24,6 +24,7 @@ export interface PlaceSyncPlanOptions<TView extends SyncableView = SyncableView>
 export declare class PlaceSyncPlan<TView extends SyncableView = SyncableView> implements DomainSyncPlan<PlaceSyncTarget> {
     private readonly options;
     readonly domain = "place";
+    readonly requiresAuth = true;
     readonly idleBackoff: SyncBackoffOptions;
     constructor(options?: PlaceSyncPlanOptions<TView>);
     supports: (target: SyncTargetDescriptor) => target is PlaceSyncTarget;

package/dist/client-socket-v2/plans/place-sync-plan.js

@@ -20,6 +20,7 @@ class PlaceSyncPlan {
         var _a;
         this.options = options;
         this.domain = 'place';
+        this.requiresAuth = true;
         this.supports = (target) => (target === null || target === void 0 ? void 0 : target.type) === 'place';
         this.getKey = (target) => { var _a; return `place:${(_a = target === null || target === void 0 ? void 0 : target.id) !== null && _a !== void 0 ? _a : ''}`; };
         this.getIntervalMs = (target) => { var _a, _b; return (_b = (_a = target.intervalMs) !== null && _a !== void 0 ? _a : this.options.intervalMs) !== null && _b !== void 0 ? _b : 2000; };

package/dist/client-socket-v2/plans/profile-sync-plan.d.ts

@@ -24,6 +24,7 @@ export interface ProfileSyncPlanOptions<TView extends SyncableView = SyncableVie
 export declare class ProfileSyncPlan<TView extends SyncableView = SyncableView> implements DomainSyncPlan<ProfileSyncTarget> {
     private readonly options;
     readonly domain = "profile";
+    readonly requiresAuth = true;
     readonly idleBackoff: SyncBackoffOptions;
     constructor(options?: ProfileSyncPlanOptions<TView>);
     supports: (target: SyncTargetDescriptor) => target is ProfileSyncTarget;

package/dist/client-socket-v2/plans/profile-sync-plan.js

@@ -20,6 +20,7 @@ class ProfileSyncPlan {
         var _a;
         this.options = options;
         this.domain = 'profile';
+        this.requiresAuth = true;
         this.supports = (target) => (target === null || target === void 0 ? void 0 : target.type) === 'profile';
         this.getKey = (target) => { var _a; return `profile:${(_a = target === null || target === void 0 ? void 0 : target.id) !== null && _a !== void 0 ? _a : ''}`; };
         this.getIntervalMs = (target) => { var _a, _b; return (_b = (_a = target.intervalMs) !== null && _a !== void 0 ? _a : this.options.intervalMs) !== null && _b !== void 0 ? _b : 2000; };

package/dist/client-socket-v2/sync-scheduler.d.ts

@@ -27,6 +27,7 @@ export declare class DomainSyncScheduler implements SyncScheduler {
     private readonly random;
     private readonly unsubs;
     constructor(options: SyncSchedulerOptions);
+    private isEntryAuthReady;
     start: (target: SyncTargetDescriptor) => void;
     stop: (target: SyncTargetDescriptor) => void;
     stopAll: () => void;
@@ -36,7 +37,11 @@ export declare class DomainSyncScheduler implements SyncScheduler {
     private resolvePlan;
     private findEntry;
     private buildContext;
+    /** run the connect-time hook (may poll the server, e.g. chat catch-up) then fresh-start the poll loop. */
+    private activateEntry;
     private handleConnected;
+    private resumeAuthGated;
+    private pauseAuthGated;
     private stopAllTimers;
     private clearTimer;
     private scheduleNow;

package/dist/client-socket-v2/sync-scheduler.js

@@ -24,6 +24,12 @@ class DomainSyncScheduler {
         this.targets = new Map();
         this.snapshots = new Map();
         this.unsubs = [];
+        this.isEntryAuthReady = (entry) => {
+            if (!entry.plan.requiresAuth)
+                return true;
+            const auth = this.options.client.auth;
+            return !!auth && auth.state === 'authenticated';
+        };
         this.start = (target) => {
             const plan = this.resolvePlan(target);
             const key = plan.getKey(target);
@@ -32,8 +38,9 @@ class DomainSyncScheduler {
                 entry.target = Object.assign(Object.assign({}, entry.target), target);
                 return;
             }
-            this.targets.set(key, { target, plan });
-            if (this.options.client.state === 'connected')
+            const created = { target, plan };
+            this.targets.set(key, created);
+            if (this.options.client.state === 'connected' && this.isEntryAuthReady(created))
                 this.scheduleNow(key);
         };
         this.stop = (target) => {
@@ -104,18 +111,40 @@ class DomainSyncScheduler {
             }),
             stop: target => this.stop(target),
         });
-        this.handleConnected = () => __awaiter(this, void 0, void 0, function* () {
+        /** run the connect-time hook (may poll the server, e.g. chat catch-up) then fresh-start the poll loop. */
+        this.activateEntry = (key, entry, ctx) => __awaiter(this, void 0, void 0, function* () {
             var _k, _l;
+            yield ((_l = (_k = entry.plan).onConnected) === null || _l === void 0 ? void 0 : _l.call(_k, entry.target, ctx));
+            entry.failures = 0;
+            entry.goneStreak = 0;
+            entry.idleStreak = 0;
+            this.scheduleNow(key);
+        });
+        this.handleConnected = () => __awaiter(this, void 0, void 0, function* () {
             const ctx = this.buildContext();
             for (const [key, entry] of this.targets.entries()) {
-                // reconnect = fresh start
-                entry.failures = 0;
-                entry.goneStreak = 0;
-                entry.idleStreak = 0;
-                yield ((_l = (_k = entry.plan).onConnected) === null || _l === void 0 ? void 0 : _l.call(_k, entry.target, ctx));
-                this.scheduleNow(key);
+                // gated (requiresAuth) entries activate on `authenticated` instead — see resumeAuthGated.
+                // onConnected itself may poll the server (chat catch-up), so it must be gated too, not just run().
+                if (!this.isEntryAuthReady(entry))
+                    continue;
+                yield this.activateEntry(key, entry, ctx);
             }
         });
+        this.resumeAuthGated = () => __awaiter(this, void 0, void 0, function* () {
+            if (this.options.client.state !== 'connected')
+                return;
+            const ctx = this.buildContext();
+            for (const [key, entry] of this.targets.entries()) {
+                if (entry.plan.requiresAuth)
+                    yield this.activateEntry(key, entry, ctx);
+            }
+        });
+        this.pauseAuthGated = () => {
+            this.targets.forEach(entry => {
+                if (entry.plan.requiresAuth)
+                    this.clearTimer(entry);
+            });
+        };
         this.stopAllTimers = () => {
             this.targets.forEach(entry => this.clearTimer(entry));
         };
@@ -143,7 +172,7 @@ class DomainSyncScheduler {
             if (!entry)
                 return;
             this.clearTimer(entry);
-            if (this.options.client.state !== 'connected')
+            if (this.options.client.state !== 'connected' || !this.isEntryAuthReady(entry))
                 return;
             const baseMs = (_d = (_a = entry.target.intervalMs) !== null && _a !== void 0 ? _a : (_c = (_b = entry.plan).getIntervalMs) === null || _c === void 0 ? void 0 : _c.call(_b, entry.target)) !== null && _d !== void 0 ? _d : 5000;
             const intervalMs = this.computeInterval(entry, baseMs);
@@ -170,7 +199,7 @@ class DomainSyncScheduler {
         this.toTimerKey = (key) => `${this.timerPrefix}${key}`;
         this.runEntry = (key) => __awaiter(this, void 0, void 0, function* () {
             const entry = this.targets.get(key);
-            if (!entry || this.options.client.state !== 'connected')
+            if (!entry || this.options.client.state !== 'connected' || !this.isEntryAuthReady(entry))
                 return;
             if (entry.inFlight)
                 return;
@@ -236,6 +265,8 @@ class DomainSyncScheduler {
                     return;
                 if (!type.startsWith(`${entry.target.type}.`))
                     return;
+                if (!this.isEntryAuthReady(entry))
+                    return;
                 // nudge resets idle backoff (best-effort)
                 entry.idleStreak = 0;
                 yield entry.plan.onTrigger(entry.target, message, ctx).catch(() => undefined);
@@ -261,6 +292,15 @@ class DomainSyncScheduler {
         this.unsubs.push(options.client.onMessage(({ message }) => {
             void this.handleTrigger(message);
         }));
+        const auth = options.client.auth;
+        if (auth) {
+            this.unsubs.push(auth.onAuthState(state => {
+                if (state === 'authenticated')
+                    void this.resumeAuthGated();
+                else
+                    this.pauseAuthGated();
+            }));
+        }
     }
 }
 exports.DomainSyncScheduler = DomainSyncScheduler;

package/dist/client-socket-v2/types.d.ts

@@ -1,5 +1,6 @@
 import type { ResolveSocketPacketType, SocketMessage, SocketPacketInputType, SocketPacketRequestData, SocketPacketResponseData, SocketPacketType } from '../lib/types';
 import type { DeviceBootstrapInput } from '../lib/device/types';
+import type { AuthController, AuthControllerOptionsPartial } from './auth-controller';
 export declare type ClientSocketState = 'idle' | 'connecting' | 'connected' | 'closing' | 'closed';
 export interface SocketLike {
     readonly readyState: number;
@@ -81,6 +82,7 @@ export interface ClientSocketOptions {
     maxPendingRequests?: number;
     keepAlive?: false | KeepAliveLoopOptionsPartial;
     reconnect?: false | AutoReconnectOptionsPartial;
+    auth?: false | AuthControllerOptionsPartial;
     createMid?: () => string;
     now?: () => number;
 }
@@ -103,6 +105,7 @@ export interface ClientSocketV2 {
     readonly timerScheduler?: SharedTimerScheduler;
     readonly keepAlive?: KeepAliveLoopControl;
     readonly reconnect?: ReconnectController;
+    readonly auth?: AuthController;
     connect(): Promise<void>;
     disconnect(code?: number, reason?: string): Promise<void>;
     send<TType extends SocketPacketInputType>(type: TType, data?: SocketPacketRequestData<ResolveSocketPacketType<TType>>): void;
@@ -163,6 +166,7 @@ export interface DomainSyncContext {
 }
 export interface DomainSyncPlan<TTarget extends SyncTargetDescriptor = SyncTargetDescriptor> {
     readonly domain: string;
+    readonly requiresAuth?: boolean;
     readonly failurePolicy?: SyncFailurePolicy;
     readonly idleBackoff?: SyncBackoffOptions;
     supports(target: SyncTargetDescriptor): target is TTarget;

package/dist/lib/auth/contracts.d.ts

@@ -0,0 +1,65 @@
+/**
+ * `lib/auth/contracts.ts`
+ * - client-safe shared auth contracts.
+ * - keep this file free from server-only runtime dependencies.
+ */
+export declare type AuthUpdateState = '' | 'pending' | 'validating' | 'authenticated' | 'failed' | 'disconnected';
+export interface AuthUserHead {
+    /** id of user */
+    id?: string;
+    /** name of user */
+    name?: string;
+}
+/** AWS Cognito temporary credential. */
+export interface AuthCredential {
+    AccessKeyId?: string;
+    SecretKey?: string;
+    SessionToken?: string;
+    /** ISO expiration timestamp */
+    Expiration?: string;
+}
+/** issued identity token bundle. */
+export interface AuthToken {
+    authId?: string;
+    accountId?: string;
+    identityId?: string;
+    identityPoolId?: string;
+    /** JWT identity token — SSoT used for HTTP `Authorization` headers */
+    identityToken?: string;
+    credential?: AuthCredential;
+}
+/** auth identity record (user/site binding) embedded in the token view. */
+export interface AuthRecord {
+    id: string;
+    accountId?: string;
+    userId?: string;
+    siteId?: string;
+    refreshedAt?: number;
+}
+/** client-safe view of the refresh/switch token payload (mirrors backend `UserTokenView`). */
+export interface AuthTokenView {
+    /** user id */
+    id: string;
+    accountId?: string;
+    /** role of the user, e.g. `guest` */
+    userRole?: string;
+    /** status of the user, e.g. `active` */
+    userStatus?: string;
+    /** issued token bundle; `Token.identityToken` is the SSoT */
+    Token?: AuthToken;
+    /** auth identity record */
+    $auth?: AuthRecord;
+    /** cloud id */
+    cloudId?: string;
+}
+/** client-safe view of the logout result (curated from backend `UserLogoutResult`). */
+export interface AuthLogoutView {
+    /** logged-out user id */
+    id?: string;
+    /** revoked auth-id */
+    authId?: string;
+    /** revoke flag (1 when revoked) */
+    revoked?: number;
+    /** revoke completion time (epoch ms) */
+    revokedAt?: number;
+}

package/dist/lib/auth/contracts.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * `lib/auth/contracts.ts`
+ * - client-safe shared auth contracts.
+ * - keep this file free from server-only runtime dependencies.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/lib/auth/types.d.ts

@@ -1,13 +1,10 @@
-import type { InferSocketError, InferSocketRequest, InferSocketResponse, SocketErrorMessage, SocketRequestMessage, SocketResponseMessage } from '../types';
-export declare type AuthUpdateState = '' | 'pending' | 'validating' | 'authenticated' | 'failed' | 'disconnected';
+import type { InferSocketError, InferSocketRequest, InferSocketResponse } from '../types';
+import type { SocketErrorMessage, SocketRequestMessage, SocketResponseMessage } from '../types';
+import { AuthUpdateState, AuthUserHead } from './contracts';
 export interface AuthUpdateRequestData {
     token?: string;
     dryRun?: boolean;
 }
-export interface AuthUpdateMemberHead {
-    id?: string;
-    name?: string;
-}
 export interface AuthUpdateResponseData {
     connId?: string;
     deviceId?: string;
@@ -16,7 +13,27 @@ export interface AuthUpdateResponseData {
     state?: AuthUpdateState;
     stateAt?: number;
     error?: string;
-    member$?: AuthUpdateMemberHead;
+    member$?: AuthUserHead;
+}
+export interface AuthRefreshRequestData {
+    /** ISO timestamp used to compute the signature */
+    current: string;
+    /** app-computed proof signature (lemon hmac) */
+    signature: string;
+    /** backend auth-id; used as `/oauth/{authId}/refresh` path */
+    authId: string;
+    /** (internal) userAgent the signature */
+    userAgent?: string;
+}
+export interface AuthSwitchRequestData extends AuthRefreshRequestData {
+    /** 전환할 사이트 ID */
+    target: string;
+}
+export interface AuthLogoutRequestData {
+    /** (internal) auth-id */
+    authId?: string;
+    /** (internal) userAgent the signature */
+    userAgent?: string;
 }
 declare module '../types' {
     interface SocketPacketRegistry {
@@ -25,6 +42,21 @@ declare module '../types' {
             response: AuthUpdateResponseData;
             error: null;
         };
+        'auth.refresh': {
+            request: AuthRefreshRequestData;
+            response: unknown;
+            error: null;
+        };
+        'auth.switch': {
+            request: AuthSwitchRequestData;
+            response: unknown;
+            error: null;
+        };
+        'auth.logout': {
+            request: AuthLogoutRequestData;
+            response: unknown;
+            error: null;
+        };
     }
 }
 export declare type AuthUpdateType = 'auth.update';
@@ -34,3 +66,24 @@ export declare type AuthUpdateErrorData = InferSocketError<AuthUpdateType>;
 export declare type AuthUpdateRequestMessage = SocketRequestMessage<AuthUpdateType>;
 export declare type AuthUpdateResponseMessage = SocketResponseMessage<AuthUpdateType>;
 export declare type AuthUpdateErrorMessage = SocketErrorMessage<AuthUpdateType>;
+export declare type AuthRefreshType = 'auth.refresh';
+export declare type AuthRefreshInput = InferSocketRequest<AuthRefreshType>;
+export declare type AuthRefreshResponse = InferSocketResponse<AuthRefreshType>;
+export declare type AuthRefreshErrorData = InferSocketError<AuthRefreshType>;
+export declare type AuthRefreshRequestMessage = SocketRequestMessage<AuthRefreshType>;
+export declare type AuthRefreshResponseMessage = SocketResponseMessage<AuthRefreshType>;
+export declare type AuthRefreshErrorMessage = SocketErrorMessage<AuthRefreshType>;
+export declare type AuthSwitchType = 'auth.switch';
+export declare type AuthSwitchInput = InferSocketRequest<AuthSwitchType>;
+export declare type AuthSwitchResponse = InferSocketResponse<AuthSwitchType>;
+export declare type AuthSwitchErrorData = InferSocketError<AuthSwitchType>;
+export declare type AuthSwitchRequestMessage = SocketRequestMessage<AuthSwitchType>;
+export declare type AuthSwitchResponseMessage = SocketResponseMessage<AuthSwitchType>;
+export declare type AuthSwitchErrorMessage = SocketErrorMessage<AuthSwitchType>;
+export declare type AuthLogoutType = 'auth.logout';
+export declare type AuthLogoutInput = InferSocketRequest<AuthLogoutType>;
+export declare type AuthLogoutResponse = InferSocketResponse<AuthLogoutType>;
+export declare type AuthLogoutErrorData = InferSocketError<AuthLogoutType>;
+export declare type AuthLogoutRequestMessage = SocketRequestMessage<AuthLogoutType>;
+export declare type AuthLogoutResponseMessage = SocketResponseMessage<AuthLogoutType>;
+export declare type AuthLogoutErrorMessage = SocketErrorMessage<AuthLogoutType>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lemoncloud/chatic-sockets-lib",
-  "version": "0.3.4",
+  "version": "0.4.1",
   "description": "Client websocket transport and sync runtime for chatic sockets v2",
   "main": "dist/client-socket-v2/index.js",
   "types": "dist/client-socket-v2/index.d.ts",