@camstack/sdk 1.2.133 → 1.2.135

package/dist/index.cjs

@@ -654,6 +654,119 @@ SuperJSON.registerCustom;
 SuperJSON.registerSymbol;
 SuperJSON.allowErrorProps;
 //#endregion
+//#region src/session-keeper.ts
+var DEFAULT_MARGIN_MS = 5 * 6e4;
+var RETRY_MS = 3e4;
+var MIN_DELAY_MS = 1e3;
+/** Decode a JWT's `exp` (seconds) to epoch ms, or `null`. Never throws. */
+function jwtExpiresAt(token) {
+	const part = token.split(".")[1];
+	if (part === void 0) return null;
+	try {
+		const base64 = part.replace(/-/g, "+").replace(/_/g, "/");
+		const json = typeof atob === "function" ? atob(base64) : Buffer.from(base64, "base64").toString("utf8");
+		const payload = JSON.parse(json);
+		if (payload === null || typeof payload !== "object") return null;
+		const exp = Reflect.get(payload, "exp");
+		return typeof exp === "number" && Number.isFinite(exp) ? exp * 1e3 : null;
+	} catch {
+		return null;
+	}
+}
+/** Is `error` the hub saying the session is over (as opposed to a transport failure)? */
+function isSessionRefusal(error) {
+	if (error === null || typeof error !== "object") return false;
+	const data = Reflect.get(error, "data");
+	const code = data !== null && typeof data === "object" ? Reflect.get(data, "code") : void 0;
+	return code === "UNAUTHORIZED" || code === "FORBIDDEN";
+}
+var SessionKeeper = class {
+	options;
+	current = null;
+	cancel = null;
+	inflight = null;
+	now;
+	setTimer;
+	constructor(options) {
+		this.options = options;
+		this.now = options.now ?? Date.now;
+		this.setTimer = options.setTimer ?? ((fn, ms) => {
+			const handle = setTimeout(fn, ms);
+			return () => clearTimeout(handle);
+		});
+	}
+	/** Take over `tokens` (a login, a restore from storage) and schedule its refresh. */
+	adopt(tokens) {
+		this.current = tokens;
+		this.schedule();
+	}
+	/** The tokens the keeper holds now. */
+	tokens() {
+		return this.current;
+	}
+	/**
+	* Refresh now if the access token expires within `marginMs` (default: the
+	* keeper's margin) — call it before reconnecting after the app was in the
+	* background. Resolves when done; concurrent callers share one refresh.
+	*/
+	async ensureFresh(marginMs = this.margin()) {
+		const current = this.current;
+		if (current?.refreshToken === void 0) return;
+		const expiresAt = this.expiresAtOf(current);
+		if (expiresAt !== null && expiresAt - this.now() > marginMs) return;
+		await this.refreshNow();
+	}
+	/** Refresh immediately. `null` when there is nothing to refresh or it failed. */
+	refreshNow() {
+		if (this.inflight !== null) return this.inflight;
+		const refreshToken = this.current?.refreshToken;
+		if (refreshToken === void 0) return Promise.resolve(null);
+		this.inflight = this.options.refresh(refreshToken).then((next) => {
+			this.current = next;
+			this.options.onTokens(next);
+			this.schedule();
+			return next;
+		}).catch((error) => {
+			if (isSessionRefusal(error)) {
+				this.stop();
+				this.current = null;
+				this.options.onExpired();
+			} else this.arm(RETRY_MS);
+			return null;
+		}).finally(() => {
+			this.inflight = null;
+		});
+		return this.inflight;
+	}
+	stop() {
+		this.cancel?.();
+		this.cancel = null;
+	}
+	margin() {
+		return this.options.marginMs ?? DEFAULT_MARGIN_MS;
+	}
+	expiresAtOf(tokens) {
+		return tokens.expiresAt ?? jwtExpiresAt(tokens.token);
+	}
+	schedule() {
+		this.stop();
+		const current = this.current;
+		if (current?.refreshToken === void 0) return;
+		const expiresAt = this.expiresAtOf(current);
+		if (expiresAt === null) return;
+		const remaining = expiresAt - this.now();
+		const margin = Math.min(this.margin(), Math.max(0, remaining / 2));
+		this.arm(Math.max(MIN_DELAY_MS, remaining - margin));
+	}
+	arm(ms) {
+		this.stop();
+		this.cancel = this.setTimer(() => {
+			this.cancel = null;
+			this.refreshNow();
+		}, ms);
+	}
+};
+//#endregion
 //#region src/system.ts
 /**
 * System — single, unified entry point for the camstack client API.
@@ -673,6 +786,27 @@ function refreshFlag(options) {
 var WS_KEEP_ALIVE_INTERVAL_MS = 1e4;
 var WS_KEEP_ALIVE_PONG_TIMEOUT_MS = 6e3;
 var WS_RECONNECT_RETRY_DELAY_MS = 2e3;
+/** Close code the hub sends a socket whose bearer resolved to nobody. */
+var SESSION_ENDED_CLOSE_CODE = 4401;
+/** A token this close to its `exp` is refreshed before it rides a handshake. */
+var HANDSHAKE_EXPIRY_SKEW_MS = 15e3;
+/**
+* Procedures a client calls BEFORE it holds a usable credential (login legs,
+* the refresh itself, the login-method list). They run over anonymous HTTP:
+* the socket answers a dead bearer by closing, and these calls are exactly
+* what recovers from one.
+*/
+var PRE_AUTH_PATHS = new Set([
+	"auth.refreshSession",
+	"auth.listLoginMethods",
+	"auth.getServerName",
+	"auth.login",
+	"auth.loginVerifyTotp",
+	"auth.loginBeginPasskey",
+	"auth.loginVerifyPasskey",
+	"auth.passkeyLoginBegin",
+	"auth.passkeyLoginFinish"
+]);
 var WS_RECONNECT_MAX_RETRY_DELAY_MS = 3e4;
 var System = class {
 	/** Active server base URL. Mutable via `switchServerUrl()` so the
@@ -685,6 +819,7 @@ var System = class {
 	onConnectionChange;
 	token;
 	getLanguage;
+	refreshCredential;
 	_trpcClient;
 	_wsClient = null;
 	/**
@@ -701,6 +836,13 @@ var System = class {
 	mirror = null;
 	mirrorInit = null;
 	connected = false;
+	/**
+	* The token the current socket's handshake carried (`undefined` token =
+	* anonymous handshake); `null` until a handshake has been attempted.
+	*/
+	_wsHandshake = null;
+	/** The token the hub closed a socket for (4401): never handshaken again. */
+	_rejectedToken;
 	connectedPromise = null;
 	_systemProxy;
 	_connectionVersion = 0;
@@ -716,6 +858,7 @@ var System = class {
 		this._serverUrl = config.serverUrl.replace(/\/+$/, "");
 		this.token = config.token;
 		this.getLanguage = config.getLanguage ?? (() => void 0);
+		this.refreshCredential = config.refreshCredential;
 		const isBrowser = typeof window !== "undefined";
 		this.useWs = config.useWebSocket ?? isBrowser;
 		this.onConnectionChange = config.onConnectionChange;
@@ -853,6 +996,7 @@ var System = class {
 		this.resetEventSubs();
 		this.connected = false;
 		this.connectedPromise = null;
+		this._wsHandshake = null;
 		this._trpcClient = this.buildTrpcClient();
 		this._systemProxy = (0, _camstack_types_client.createSystemProxy)(this._trpcClient);
 	}
@@ -1123,6 +1267,16 @@ var System = class {
 		this.token = token;
 	}
 	/**
+	* True when the live WebSocket was handshaken with a token other than the
+	* current one (anonymous, or rotated since). The socket authenticates once,
+	* at the handshake, so such a socket answers every protected call
+	* UNAUTHORIZED until `reconnect()`. Always false for HTTP transport.
+	*/
+	isSocketTokenStale() {
+		if (!this.useWs || this._wsHandshake === null) return false;
+		return this._wsHandshake.token !== this.token;
+	}
+	/**
 	* Synchronous snapshot of every device matching the optional filters.
 	* Backed by the `SystemMirror` warm-boot cache — call `init()` first
 	* (or `awaitReady()`) before invoking. Returns an empty array if the
@@ -1352,6 +1506,27 @@ var System = class {
 	get wsClient() {
 		return this._wsClient;
 	}
+	/**
+	* The token the next socket handshake may carry. An expired token, or one
+	* the hub just closed with 4401, is never sent: the credential is refreshed
+	* over HTTP first, and when that does not yield a usable token the
+	* handshake is anonymous (the app learns of a refused refresh from its
+	* session keeper and routes to login; a transient failure retries later).
+	*/
+	async handshakeToken() {
+		const dead = (token) => {
+			if (token === this._rejectedToken) return true;
+			const exp = jwtExpiresAt(token);
+			return exp !== null && exp - Date.now() <= HANDSHAKE_EXPIRY_SKEW_MS;
+		};
+		const initial = this.token;
+		if (initial === void 0 || !dead(initial)) return initial;
+		if (this.refreshCredential !== void 0) try {
+			await this.refreshCredential(initial === this._rejectedToken ? "rejected" : "expired");
+		} catch {}
+		const current = this.token;
+		return current !== void 0 && !dead(current) ? current : void 0;
+	}
 	buildTrpcClient() {
 		const headers = () => {
 			const h = {};
@@ -1367,10 +1542,12 @@ var System = class {
 			const epoch = this._wsEpoch;
 			this._wsClient = (0, _trpc_client.createWSClient)({
 				url: wsUrl,
-				connectionParams: () => {
+				connectionParams: async () => {
+					const token = await this.handshakeToken();
+					if (epoch === this._wsEpoch) this._wsHandshake = { token };
 					const lang = this.getLanguage();
 					return {
-						...this.token !== void 0 ? { token: this.token } : {},
+						...token !== void 0 ? { token } : {},
 						...lang ? { lang } : {}
 					};
 				},
@@ -1385,14 +1562,27 @@ var System = class {
 					this._connectionVersion += 1;
 					this.emitConnectionEvent("connected");
 				},
-				onClose: () => {
+				onClose: (cause) => {
 					if (epoch !== this._wsEpoch) return;
+					if (cause?.code === SESSION_ENDED_CLOSE_CODE) this._rejectedToken = this._wsHandshake?.token ?? this._rejectedToken;
 					this.emitConnectionEvent("disconnected");
 				}
 			});
-			return (0, _trpc_client.createTRPCClient)({ links: [(0, _trpc_client.wsLink)({
-				client: this._wsClient,
-				transformer: SuperJSON
+			const anonymousHeaders = () => {
+				const lang = this.getLanguage();
+				return lang ? { "x-camstack-lang": lang } : {};
+			};
+			return (0, _trpc_client.createTRPCClient)({ links: [(0, _trpc_client.splitLink)({
+				condition: (op) => PRE_AUTH_PATHS.has(op.path),
+				true: (0, _trpc_client.httpLink)({
+					url: `${this._serverUrl}/trpc`,
+					headers: anonymousHeaders,
+					transformer: SuperJSON
+				}),
+				false: (0, _trpc_client.wsLink)({
+					client: this._wsClient,
+					transformer: SuperJSON
+				})
 			})] });
 		}
 		this._wsClient = null;
@@ -1461,119 +1651,6 @@ async function raceFastestEndpoint(candidates, timeoutMs) {
 	}
 }
 //#endregion
-//#region src/session-keeper.ts
-var DEFAULT_MARGIN_MS = 5 * 6e4;
-var RETRY_MS = 3e4;
-var MIN_DELAY_MS = 1e3;
-/** Decode a JWT's `exp` (seconds) to epoch ms, or `null`. Never throws. */
-function jwtExpiresAt(token) {
-	const part = token.split(".")[1];
-	if (part === void 0) return null;
-	try {
-		const base64 = part.replace(/-/g, "+").replace(/_/g, "/");
-		const json = typeof atob === "function" ? atob(base64) : Buffer.from(base64, "base64").toString("utf8");
-		const payload = JSON.parse(json);
-		if (payload === null || typeof payload !== "object") return null;
-		const exp = Reflect.get(payload, "exp");
-		return typeof exp === "number" && Number.isFinite(exp) ? exp * 1e3 : null;
-	} catch {
-		return null;
-	}
-}
-/** Is `error` the hub saying the session is over (as opposed to a transport failure)? */
-function isSessionRefusal(error) {
-	if (error === null || typeof error !== "object") return false;
-	const data = Reflect.get(error, "data");
-	const code = data !== null && typeof data === "object" ? Reflect.get(data, "code") : void 0;
-	return code === "UNAUTHORIZED" || code === "FORBIDDEN";
-}
-var SessionKeeper = class {
-	options;
-	current = null;
-	cancel = null;
-	inflight = null;
-	now;
-	setTimer;
-	constructor(options) {
-		this.options = options;
-		this.now = options.now ?? Date.now;
-		this.setTimer = options.setTimer ?? ((fn, ms) => {
-			const handle = setTimeout(fn, ms);
-			return () => clearTimeout(handle);
-		});
-	}
-	/** Take over `tokens` (a login, a restore from storage) and schedule its refresh. */
-	adopt(tokens) {
-		this.current = tokens;
-		this.schedule();
-	}
-	/** The tokens the keeper holds now. */
-	tokens() {
-		return this.current;
-	}
-	/**
-	* Refresh now if the access token expires within `marginMs` (default: the
-	* keeper's margin) — call it before reconnecting after the app was in the
-	* background. Resolves when done; concurrent callers share one refresh.
-	*/
-	async ensureFresh(marginMs = this.margin()) {
-		const current = this.current;
-		if (current?.refreshToken === void 0) return;
-		const expiresAt = this.expiresAtOf(current);
-		if (expiresAt !== null && expiresAt - this.now() > marginMs) return;
-		await this.refreshNow();
-	}
-	/** Refresh immediately. `null` when there is nothing to refresh or it failed. */
-	refreshNow() {
-		if (this.inflight !== null) return this.inflight;
-		const refreshToken = this.current?.refreshToken;
-		if (refreshToken === void 0) return Promise.resolve(null);
-		this.inflight = this.options.refresh(refreshToken).then((next) => {
-			this.current = next;
-			this.options.onTokens(next);
-			this.schedule();
-			return next;
-		}).catch((error) => {
-			if (isSessionRefusal(error)) {
-				this.stop();
-				this.current = null;
-				this.options.onExpired();
-			} else this.arm(RETRY_MS);
-			return null;
-		}).finally(() => {
-			this.inflight = null;
-		});
-		return this.inflight;
-	}
-	stop() {
-		this.cancel?.();
-		this.cancel = null;
-	}
-	margin() {
-		return this.options.marginMs ?? DEFAULT_MARGIN_MS;
-	}
-	expiresAtOf(tokens) {
-		return tokens.expiresAt ?? jwtExpiresAt(tokens.token);
-	}
-	schedule() {
-		this.stop();
-		const current = this.current;
-		if (current?.refreshToken === void 0) return;
-		const expiresAt = this.expiresAtOf(current);
-		if (expiresAt === null) return;
-		const remaining = expiresAt - this.now();
-		const margin = Math.min(this.margin(), Math.max(0, remaining / 2));
-		this.arm(Math.max(MIN_DELAY_MS, remaining - margin));
-	}
-	arm(ms) {
-		this.stop();
-		this.cancel = this.setTimer(() => {
-			this.cancel = null;
-			this.refreshNow();
-		}, ms);
-	}
-};
-//#endregion
 //#region src/detection.ts
 /**
 * Detection classes — shared between CamStack app and proxy.

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { System, createSystem, raceFastestEndpoint } from "./system.js";
 export type { LoginOptions, LoginOutcome, RefreshedSession } from "./system.js";
 export { isSessionRefusal, jwtExpiresAt, SessionKeeper, type SessionKeeperOptions, type SessionTokens } from "./session-keeper.js";
-export type { SystemConfig, UserInfo, SystemLiveEvent, SystemLiveEventListener, SecondFactorKind } from "./system.js";
+export type { SystemConfig, CredentialRefreshReason, UserInfo, SystemLiveEvent, SystemLiveEventListener, SecondFactorKind } from "./system.js";
 export type { DeviceInfo } from "@camstack/types";
 export type { BackendAppRouter } from "./backend-router.js";
 export type { BackendAppRouter as AppRouter } from "./backend-router.js";

package/dist/index.js

@@ -1,4 +1,4 @@
-import { createTRPCClient, createWSClient, httpLink, wsLink } from "@trpc/client";
+import { createTRPCClient, createWSClient, httpLink, splitLink, wsLink } from "@trpc/client";
 import { SystemMirror, createSystemProxy } from "@camstack/types/client";
 //#region ../../node_modules/superjson/dist/double-indexed-kv.js
 var DoubleIndexedKV = class {
@@ -653,6 +653,119 @@ SuperJSON.registerCustom;
 SuperJSON.registerSymbol;
 SuperJSON.allowErrorProps;
 //#endregion
+//#region src/session-keeper.ts
+var DEFAULT_MARGIN_MS = 5 * 6e4;
+var RETRY_MS = 3e4;
+var MIN_DELAY_MS = 1e3;
+/** Decode a JWT's `exp` (seconds) to epoch ms, or `null`. Never throws. */
+function jwtExpiresAt(token) {
+	const part = token.split(".")[1];
+	if (part === void 0) return null;
+	try {
+		const base64 = part.replace(/-/g, "+").replace(/_/g, "/");
+		const json = typeof atob === "function" ? atob(base64) : Buffer.from(base64, "base64").toString("utf8");
+		const payload = JSON.parse(json);
+		if (payload === null || typeof payload !== "object") return null;
+		const exp = Reflect.get(payload, "exp");
+		return typeof exp === "number" && Number.isFinite(exp) ? exp * 1e3 : null;
+	} catch {
+		return null;
+	}
+}
+/** Is `error` the hub saying the session is over (as opposed to a transport failure)? */
+function isSessionRefusal(error) {
+	if (error === null || typeof error !== "object") return false;
+	const data = Reflect.get(error, "data");
+	const code = data !== null && typeof data === "object" ? Reflect.get(data, "code") : void 0;
+	return code === "UNAUTHORIZED" || code === "FORBIDDEN";
+}
+var SessionKeeper = class {
+	options;
+	current = null;
+	cancel = null;
+	inflight = null;
+	now;
+	setTimer;
+	constructor(options) {
+		this.options = options;
+		this.now = options.now ?? Date.now;
+		this.setTimer = options.setTimer ?? ((fn, ms) => {
+			const handle = setTimeout(fn, ms);
+			return () => clearTimeout(handle);
+		});
+	}
+	/** Take over `tokens` (a login, a restore from storage) and schedule its refresh. */
+	adopt(tokens) {
+		this.current = tokens;
+		this.schedule();
+	}
+	/** The tokens the keeper holds now. */
+	tokens() {
+		return this.current;
+	}
+	/**
+	* Refresh now if the access token expires within `marginMs` (default: the
+	* keeper's margin) — call it before reconnecting after the app was in the
+	* background. Resolves when done; concurrent callers share one refresh.
+	*/
+	async ensureFresh(marginMs = this.margin()) {
+		const current = this.current;
+		if (current?.refreshToken === void 0) return;
+		const expiresAt = this.expiresAtOf(current);
+		if (expiresAt !== null && expiresAt - this.now() > marginMs) return;
+		await this.refreshNow();
+	}
+	/** Refresh immediately. `null` when there is nothing to refresh or it failed. */
+	refreshNow() {
+		if (this.inflight !== null) return this.inflight;
+		const refreshToken = this.current?.refreshToken;
+		if (refreshToken === void 0) return Promise.resolve(null);
+		this.inflight = this.options.refresh(refreshToken).then((next) => {
+			this.current = next;
+			this.options.onTokens(next);
+			this.schedule();
+			return next;
+		}).catch((error) => {
+			if (isSessionRefusal(error)) {
+				this.stop();
+				this.current = null;
+				this.options.onExpired();
+			} else this.arm(RETRY_MS);
+			return null;
+		}).finally(() => {
+			this.inflight = null;
+		});
+		return this.inflight;
+	}
+	stop() {
+		this.cancel?.();
+		this.cancel = null;
+	}
+	margin() {
+		return this.options.marginMs ?? DEFAULT_MARGIN_MS;
+	}
+	expiresAtOf(tokens) {
+		return tokens.expiresAt ?? jwtExpiresAt(tokens.token);
+	}
+	schedule() {
+		this.stop();
+		const current = this.current;
+		if (current?.refreshToken === void 0) return;
+		const expiresAt = this.expiresAtOf(current);
+		if (expiresAt === null) return;
+		const remaining = expiresAt - this.now();
+		const margin = Math.min(this.margin(), Math.max(0, remaining / 2));
+		this.arm(Math.max(MIN_DELAY_MS, remaining - margin));
+	}
+	arm(ms) {
+		this.stop();
+		this.cancel = this.setTimer(() => {
+			this.cancel = null;
+			this.refreshNow();
+		}, ms);
+	}
+};
+//#endregion
 //#region src/system.ts
 /**
 * System — single, unified entry point for the camstack client API.
@@ -672,6 +785,27 @@ function refreshFlag(options) {
 var WS_KEEP_ALIVE_INTERVAL_MS = 1e4;
 var WS_KEEP_ALIVE_PONG_TIMEOUT_MS = 6e3;
 var WS_RECONNECT_RETRY_DELAY_MS = 2e3;
+/** Close code the hub sends a socket whose bearer resolved to nobody. */
+var SESSION_ENDED_CLOSE_CODE = 4401;
+/** A token this close to its `exp` is refreshed before it rides a handshake. */
+var HANDSHAKE_EXPIRY_SKEW_MS = 15e3;
+/**
+* Procedures a client calls BEFORE it holds a usable credential (login legs,
+* the refresh itself, the login-method list). They run over anonymous HTTP:
+* the socket answers a dead bearer by closing, and these calls are exactly
+* what recovers from one.
+*/
+var PRE_AUTH_PATHS = new Set([
+	"auth.refreshSession",
+	"auth.listLoginMethods",
+	"auth.getServerName",
+	"auth.login",
+	"auth.loginVerifyTotp",
+	"auth.loginBeginPasskey",
+	"auth.loginVerifyPasskey",
+	"auth.passkeyLoginBegin",
+	"auth.passkeyLoginFinish"
+]);
 var WS_RECONNECT_MAX_RETRY_DELAY_MS = 3e4;
 var System = class {
 	/** Active server base URL. Mutable via `switchServerUrl()` so the
@@ -684,6 +818,7 @@ var System = class {
 	onConnectionChange;
 	token;
 	getLanguage;
+	refreshCredential;
 	_trpcClient;
 	_wsClient = null;
 	/**
@@ -700,6 +835,13 @@ var System = class {
 	mirror = null;
 	mirrorInit = null;
 	connected = false;
+	/**
+	* The token the current socket's handshake carried (`undefined` token =
+	* anonymous handshake); `null` until a handshake has been attempted.
+	*/
+	_wsHandshake = null;
+	/** The token the hub closed a socket for (4401): never handshaken again. */
+	_rejectedToken;
 	connectedPromise = null;
 	_systemProxy;
 	_connectionVersion = 0;
@@ -715,6 +857,7 @@ var System = class {
 		this._serverUrl = config.serverUrl.replace(/\/+$/, "");
 		this.token = config.token;
 		this.getLanguage = config.getLanguage ?? (() => void 0);
+		this.refreshCredential = config.refreshCredential;
 		const isBrowser = typeof window !== "undefined";
 		this.useWs = config.useWebSocket ?? isBrowser;
 		this.onConnectionChange = config.onConnectionChange;
@@ -852,6 +995,7 @@ var System = class {
 		this.resetEventSubs();
 		this.connected = false;
 		this.connectedPromise = null;
+		this._wsHandshake = null;
 		this._trpcClient = this.buildTrpcClient();
 		this._systemProxy = createSystemProxy(this._trpcClient);
 	}
@@ -1122,6 +1266,16 @@ var System = class {
 		this.token = token;
 	}
 	/**
+	* True when the live WebSocket was handshaken with a token other than the
+	* current one (anonymous, or rotated since). The socket authenticates once,
+	* at the handshake, so such a socket answers every protected call
+	* UNAUTHORIZED until `reconnect()`. Always false for HTTP transport.
+	*/
+	isSocketTokenStale() {
+		if (!this.useWs || this._wsHandshake === null) return false;
+		return this._wsHandshake.token !== this.token;
+	}
+	/**
 	* Synchronous snapshot of every device matching the optional filters.
 	* Backed by the `SystemMirror` warm-boot cache — call `init()` first
 	* (or `awaitReady()`) before invoking. Returns an empty array if the
@@ -1351,6 +1505,27 @@ var System = class {
 	get wsClient() {
 		return this._wsClient;
 	}
+	/**
+	* The token the next socket handshake may carry. An expired token, or one
+	* the hub just closed with 4401, is never sent: the credential is refreshed
+	* over HTTP first, and when that does not yield a usable token the
+	* handshake is anonymous (the app learns of a refused refresh from its
+	* session keeper and routes to login; a transient failure retries later).
+	*/
+	async handshakeToken() {
+		const dead = (token) => {
+			if (token === this._rejectedToken) return true;
+			const exp = jwtExpiresAt(token);
+			return exp !== null && exp - Date.now() <= HANDSHAKE_EXPIRY_SKEW_MS;
+		};
+		const initial = this.token;
+		if (initial === void 0 || !dead(initial)) return initial;
+		if (this.refreshCredential !== void 0) try {
+			await this.refreshCredential(initial === this._rejectedToken ? "rejected" : "expired");
+		} catch {}
+		const current = this.token;
+		return current !== void 0 && !dead(current) ? current : void 0;
+	}
 	buildTrpcClient() {
 		const headers = () => {
 			const h = {};
@@ -1366,10 +1541,12 @@ var System = class {
 			const epoch = this._wsEpoch;
 			this._wsClient = createWSClient({
 				url: wsUrl,
-				connectionParams: () => {
+				connectionParams: async () => {
+					const token = await this.handshakeToken();
+					if (epoch === this._wsEpoch) this._wsHandshake = { token };
 					const lang = this.getLanguage();
 					return {
-						...this.token !== void 0 ? { token: this.token } : {},
+						...token !== void 0 ? { token } : {},
 						...lang ? { lang } : {}
 					};
 				},
@@ -1384,14 +1561,27 @@ var System = class {
 					this._connectionVersion += 1;
 					this.emitConnectionEvent("connected");
 				},
-				onClose: () => {
+				onClose: (cause) => {
 					if (epoch !== this._wsEpoch) return;
+					if (cause?.code === SESSION_ENDED_CLOSE_CODE) this._rejectedToken = this._wsHandshake?.token ?? this._rejectedToken;
 					this.emitConnectionEvent("disconnected");
 				}
 			});
-			return createTRPCClient({ links: [wsLink({
-				client: this._wsClient,
-				transformer: SuperJSON
+			const anonymousHeaders = () => {
+				const lang = this.getLanguage();
+				return lang ? { "x-camstack-lang": lang } : {};
+			};
+			return createTRPCClient({ links: [splitLink({
+				condition: (op) => PRE_AUTH_PATHS.has(op.path),
+				true: httpLink({
+					url: `${this._serverUrl}/trpc`,
+					headers: anonymousHeaders,
+					transformer: SuperJSON
+				}),
+				false: wsLink({
+					client: this._wsClient,
+					transformer: SuperJSON
+				})
 			})] });
 		}
 		this._wsClient = null;
@@ -1460,119 +1650,6 @@ async function raceFastestEndpoint(candidates, timeoutMs) {
 	}
 }
 //#endregion
-//#region src/session-keeper.ts
-var DEFAULT_MARGIN_MS = 5 * 6e4;
-var RETRY_MS = 3e4;
-var MIN_DELAY_MS = 1e3;
-/** Decode a JWT's `exp` (seconds) to epoch ms, or `null`. Never throws. */
-function jwtExpiresAt(token) {
-	const part = token.split(".")[1];
-	if (part === void 0) return null;
-	try {
-		const base64 = part.replace(/-/g, "+").replace(/_/g, "/");
-		const json = typeof atob === "function" ? atob(base64) : Buffer.from(base64, "base64").toString("utf8");
-		const payload = JSON.parse(json);
-		if (payload === null || typeof payload !== "object") return null;
-		const exp = Reflect.get(payload, "exp");
-		return typeof exp === "number" && Number.isFinite(exp) ? exp * 1e3 : null;
-	} catch {
-		return null;
-	}
-}
-/** Is `error` the hub saying the session is over (as opposed to a transport failure)? */
-function isSessionRefusal(error) {
-	if (error === null || typeof error !== "object") return false;
-	const data = Reflect.get(error, "data");
-	const code = data !== null && typeof data === "object" ? Reflect.get(data, "code") : void 0;
-	return code === "UNAUTHORIZED" || code === "FORBIDDEN";
-}
-var SessionKeeper = class {
-	options;
-	current = null;
-	cancel = null;
-	inflight = null;
-	now;
-	setTimer;
-	constructor(options) {
-		this.options = options;
-		this.now = options.now ?? Date.now;
-		this.setTimer = options.setTimer ?? ((fn, ms) => {
-			const handle = setTimeout(fn, ms);
-			return () => clearTimeout(handle);
-		});
-	}
-	/** Take over `tokens` (a login, a restore from storage) and schedule its refresh. */
-	adopt(tokens) {
-		this.current = tokens;
-		this.schedule();
-	}
-	/** The tokens the keeper holds now. */
-	tokens() {
-		return this.current;
-	}
-	/**
-	* Refresh now if the access token expires within `marginMs` (default: the
-	* keeper's margin) — call it before reconnecting after the app was in the
-	* background. Resolves when done; concurrent callers share one refresh.
-	*/
-	async ensureFresh(marginMs = this.margin()) {
-		const current = this.current;
-		if (current?.refreshToken === void 0) return;
-		const expiresAt = this.expiresAtOf(current);
-		if (expiresAt !== null && expiresAt - this.now() > marginMs) return;
-		await this.refreshNow();
-	}
-	/** Refresh immediately. `null` when there is nothing to refresh or it failed. */
-	refreshNow() {
-		if (this.inflight !== null) return this.inflight;
-		const refreshToken = this.current?.refreshToken;
-		if (refreshToken === void 0) return Promise.resolve(null);
-		this.inflight = this.options.refresh(refreshToken).then((next) => {
-			this.current = next;
-			this.options.onTokens(next);
-			this.schedule();
-			return next;
-		}).catch((error) => {
-			if (isSessionRefusal(error)) {
-				this.stop();
-				this.current = null;
-				this.options.onExpired();
-			} else this.arm(RETRY_MS);
-			return null;
-		}).finally(() => {
-			this.inflight = null;
-		});
-		return this.inflight;
-	}
-	stop() {
-		this.cancel?.();
-		this.cancel = null;
-	}
-	margin() {
-		return this.options.marginMs ?? DEFAULT_MARGIN_MS;
-	}
-	expiresAtOf(tokens) {
-		return tokens.expiresAt ?? jwtExpiresAt(tokens.token);
-	}
-	schedule() {
-		this.stop();
-		const current = this.current;
-		if (current?.refreshToken === void 0) return;
-		const expiresAt = this.expiresAtOf(current);
-		if (expiresAt === null) return;
-		const remaining = expiresAt - this.now();
-		const margin = Math.min(this.margin(), Math.max(0, remaining / 2));
-		this.arm(Math.max(MIN_DELAY_MS, remaining - margin));
-	}
-	arm(ms) {
-		this.stop();
-		this.cancel = this.setTimer(() => {
-			this.cancel = null;
-			this.refreshNow();
-		}, ms);
-	}
-};
-//#endregion
 //#region src/detection.ts
 /**
 * Detection classes — shared between CamStack app and proxy.

package/dist/system.d.ts

@@ -56,7 +56,18 @@ export interface SystemConfig {
 	* from `Accept-Language`.
 	*/
 	readonly getLanguage?: () => string | undefined;
+	/**
+	* Obtain a fresh access token (normally `SessionKeeper.refreshNow` /
+	* `ensureFresh`, which ends in `setToken`). Called BEFORE a socket handshake
+	* whose token is expired or was just refused with close code 4401. The
+	* refresh itself runs over HTTP (`refreshSession` never uses the socket). A
+	* rejection is swallowed: the handshake then goes out anonymous rather than
+	* carrying a token the hub is known to refuse.
+	*/
+	readonly refreshCredential?: (reason: CredentialRefreshReason) => Promise<void>;
 }
+/** Why `SystemConfig.refreshCredential` is asked: the token's own `exp`, or a 4401 close. */
+export type CredentialRefreshReason = "expired" | "rejected";
 type ConnectionListener = (state: BackendConnectionState, version: number) => void;
 /** Options of every login leg. */
 export interface LoginOptions {
@@ -114,6 +125,7 @@ export declare class System {
 	private readonly onConnectionChange;
 	private token;
 	private readonly getLanguage;
+	private readonly refreshCredential;
 	private _trpcClient;
 	private _wsClient;
 	/**
@@ -130,6 +142,13 @@ export declare class System {
 	private mirror;
 	private mirrorInit;
 	private connected;
+	/**
+	* The token the current socket's handshake carried (`undefined` token =
+	* anonymous handshake); `null` until a handshake has been attempted.
+	*/
+	private _wsHandshake;
+	/** The token the hub closed a socket for (4401): never handshaken again. */
+	private _rejectedToken;
 	private connectedPromise;
 	private _systemProxy;
 	private _connectionVersion;
@@ -388,6 +407,13 @@ export declare class System {
 	/** Update the auth token (e.g. after login or token refresh). */
 	setToken(token: string): void;
 	/**
+	* True when the live WebSocket was handshaken with a token other than the
+	* current one (anonymous, or rotated since). The socket authenticates once,
+	* at the handshake, so such a socket answers every protected call
+	* UNAUTHORIZED until `reconnect()`. Always false for HTTP transport.
+	*/
+	isSocketTokenStale(): boolean;
+	/**
 	* Synchronous snapshot of every device matching the optional filters.
 	* Backed by the `SystemMirror` warm-boot cache — call `init()` first
 	* (or `awaitReady()`) before invoking. Returns an empty array if the
@@ -494,6 +520,14 @@ export declare class System {
 	* (e.g. for keep-alive metrics). Rebuilt on `reconnect()`.
 	*/
 	get wsClient(): TrpcWsClient | null;
+	/**
+	* The token the next socket handshake may carry. An expired token, or one
+	* the hub just closed with 4401, is never sent: the credential is refreshed
+	* over HTTP first, and when that does not yield a usable token the
+	* handshake is anonymous (the app learns of a refused refresh from its
+	* session keeper and routes to login; a transient failure retries later).
+	*/
+	private handshakeToken;
 	private buildTrpcClient;
 }
 /** Create a `System` instance. Convenience factory. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/sdk",
-  "version": "1.2.133",
+  "version": "1.2.135",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",