@camstack/sdk 1.2.127 → 1.2.128

package/dist/__tests__/session-keeper.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.cjs

@@ -667,6 +667,9 @@ SuperJSON.allowErrorProps;
 * ui-library Provider can seed React Query with the same WS connection
 * — a future phase will narrow the surface further.
 */
+function refreshFlag(options) {
+	return options.refreshable === true ? { refreshable: true } : {};
+}
 var WS_KEEP_ALIVE_INTERVAL_MS = 1e4;
 var WS_KEEP_ALIVE_PONG_TIMEOUT_MS = 6e3;
 var WS_RECONNECT_RETRY_DELAY_MS = 2e3;
@@ -946,10 +949,11 @@ var System = class {
 		this.mirror = null;
 		this.mirrorInit = null;
 	}
-	async login(username, password) {
+	async login(username, password, options = {}) {
 		const result = await this._trpcClient.auth.login.mutate({
 			username,
-			password
+			password,
+			...refreshFlag(options)
 		});
 		if (typeof result === "object" && result !== null && "token" in result) {
 			const r = result;
@@ -966,10 +970,11 @@ var System = class {
 	* server mints the real session JWT, which we set as the active
 	* token on this client.
 	*/
-	async loginVerifyTotp(challengeToken, code) {
+	async loginVerifyTotp(challengeToken, code, options = {}) {
 		const result = await this._trpcClient.auth.loginVerifyTotp.mutate({
 			challengeToken,
-			code
+			code,
+			...refreshFlag(options)
 		});
 		if (typeof result === "object" && result !== null && "token" in result) {
 			const token = result.token;
@@ -990,10 +995,11 @@ var System = class {
 	* success the server mints the real session JWT, which we set as the
 	* active token on this client.
 	*/
-	async loginVerifyPasskey(challengeToken, response) {
+	async loginVerifyPasskey(challengeToken, response, options = {}) {
 		const result = await this._trpcClient.auth.loginVerifyPasskey.mutate({
 			challengeToken,
-			response
+			response,
+			...refreshFlag(options)
 		});
 		if (typeof result === "object" && result !== null && "token" in result) {
 			const token = result.token;
@@ -1022,8 +1028,11 @@ var System = class {
 	* `secondFactors`. That token is NOT persisted as the active session
 	* — the caller completes the remaining factor via `loginVerifyTotp`.
 	*/
-	async passkeyLoginFinish(response) {
-		const result = await this._trpcClient.auth.passkeyLoginFinish.mutate({ response });
+	async passkeyLoginFinish(response, options = {}) {
+		const result = await this._trpcClient.auth.passkeyLoginFinish.mutate({
+			response,
+			...refreshFlag(options)
+		});
 		if (typeof result === "object" && result !== null && "token" in result) {
 			const r = result;
 			const requiresSecondFactor = r.requiresTotp === true || Array.isArray(r.secondFactors) && r.secondFactors.length > 0;
@@ -1031,8 +1040,22 @@ var System = class {
 		}
 		return result;
 	}
-	async logout() {
-		await this._trpcClient.auth.logout.mutate();
+	/**
+	* Swap a refresh token for a new access token and a ROTATED refresh token
+	* (the old one stops working). Sets the new access token on this client.
+	* Throws a tRPC UNAUTHORIZED when the session is over — sign in again.
+	*/
+	async refreshSession(refreshToken) {
+		const result = await this._trpcClient.auth.refreshSession.mutate({ refreshToken });
+		this.setToken(result.token);
+		return result;
+	}
+	/**
+	* End this session on the hub (its tokens stop working at once);
+	* `everywhere: true` ends every session of the user.
+	*/
+	async logout(options = {}) {
+		await this._trpcClient.auth.logout.mutate(options.everywhere === true ? { everywhere: true } : void 0);
 	}
 	async getMe() {
 		return await this._trpcClient.auth.me.query();
@@ -1046,8 +1069,25 @@ var System = class {
 	async confirmOwnTotp(input) {
 		return await this._trpcClient.auth.confirmOwnTotp.mutate(input);
 	}
-	async disableOwnTotp() {
-		return await this._trpcClient.auth.disableOwnTotp.mutate();
+	/** Needs a fresh `reauthToken` from {@link reauthenticate}. */
+	async disableOwnTotp(input) {
+		return await this._trpcClient.auth.disableOwnTotp.mutate(input);
+	}
+	/**
+	* Re-authentication, passkey path step 1: assertion options for the
+	* caller's own passkeys. Feed `optionsJSON` to `startAuthentication`, then
+	* pass the result to {@link reauthenticate} as `passkeyResponse`.
+	*/
+	async reauthBeginPasskey() {
+		return await this._trpcClient.auth.reauthBeginPasskey.mutate();
+	}
+	/**
+	* Prove it is you — the current password or a passkey assertion — for a
+	* 5-minute `reauthToken`, required by `disableOwnTotp`, `removeOwnPasskey`
+	* and `auth.beginExternalLink` (valid only in this session).
+	*/
+	async reauthenticate(input) {
+		return await this._trpcClient.auth.reauthenticate.mutate(input);
 	}
 	async getOwnTotpStatus() {
 		return await this._trpcClient.auth.getOwnTotpStatus.query();
@@ -1061,6 +1101,7 @@ var System = class {
 	async listOwnPasskeys() {
 		return await this._trpcClient.auth.listOwnPasskeys.query();
 	}
+	/** Needs a fresh `reauthToken` from {@link reauthenticate}. */
 	async removeOwnPasskey(input) {
 		return await this._trpcClient.auth.removeOwnPasskey.mutate(input);
 	}
@@ -1410,6 +1451,119 @@ 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.
@@ -1724,6 +1878,7 @@ function getClassesForTimelinePreset(preset, customClasses) {
 //#endregion
 exports.DEFAULT_ENABLED_CLASSES = DEFAULT_ENABLED_CLASSES;
 exports.DetectionClass = DetectionClass;
+exports.SessionKeeper = SessionKeeper;
 exports.System = System;
 exports.TIMELINE_PRESET_ALL = TIMELINE_PRESET_ALL;
 exports.TIMELINE_PRESET_CRITICAL = TIMELINE_PRESET_CRITICAL;
@@ -1749,7 +1904,9 @@ exports.isPackageClassname = isPackageClassname;
 exports.isPersonClassname = isPersonClassname;
 exports.isPlateClassname = isPlateClassname;
 exports.isSensorLabelClassname = isSensorLabelClassname;
+exports.isSessionRefusal = isSessionRefusal;
 exports.isVehicleClassname = isVehicleClassname;
+exports.jwtExpiresAt = jwtExpiresAt;
 exports.licensePlateClasses = licensePlateClasses;
 exports.motionClasses = motionClasses;
 exports.packageClasses = packageClasses;

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 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 { DeviceInfo } from '@camstack/types';
 export type { BackendAppRouter } from './backend-router.js';

package/dist/index.js

@@ -666,6 +666,9 @@ SuperJSON.allowErrorProps;
 * ui-library Provider can seed React Query with the same WS connection
 * — a future phase will narrow the surface further.
 */
+function refreshFlag(options) {
+	return options.refreshable === true ? { refreshable: true } : {};
+}
 var WS_KEEP_ALIVE_INTERVAL_MS = 1e4;
 var WS_KEEP_ALIVE_PONG_TIMEOUT_MS = 6e3;
 var WS_RECONNECT_RETRY_DELAY_MS = 2e3;
@@ -945,10 +948,11 @@ var System = class {
 		this.mirror = null;
 		this.mirrorInit = null;
 	}
-	async login(username, password) {
+	async login(username, password, options = {}) {
 		const result = await this._trpcClient.auth.login.mutate({
 			username,
-			password
+			password,
+			...refreshFlag(options)
 		});
 		if (typeof result === "object" && result !== null && "token" in result) {
 			const r = result;
@@ -965,10 +969,11 @@ var System = class {
 	* server mints the real session JWT, which we set as the active
 	* token on this client.
 	*/
-	async loginVerifyTotp(challengeToken, code) {
+	async loginVerifyTotp(challengeToken, code, options = {}) {
 		const result = await this._trpcClient.auth.loginVerifyTotp.mutate({
 			challengeToken,
-			code
+			code,
+			...refreshFlag(options)
 		});
 		if (typeof result === "object" && result !== null && "token" in result) {
 			const token = result.token;
@@ -989,10 +994,11 @@ var System = class {
 	* success the server mints the real session JWT, which we set as the
 	* active token on this client.
 	*/
-	async loginVerifyPasskey(challengeToken, response) {
+	async loginVerifyPasskey(challengeToken, response, options = {}) {
 		const result = await this._trpcClient.auth.loginVerifyPasskey.mutate({
 			challengeToken,
-			response
+			response,
+			...refreshFlag(options)
 		});
 		if (typeof result === "object" && result !== null && "token" in result) {
 			const token = result.token;
@@ -1021,8 +1027,11 @@ var System = class {
 	* `secondFactors`. That token is NOT persisted as the active session
 	* — the caller completes the remaining factor via `loginVerifyTotp`.
 	*/
-	async passkeyLoginFinish(response) {
-		const result = await this._trpcClient.auth.passkeyLoginFinish.mutate({ response });
+	async passkeyLoginFinish(response, options = {}) {
+		const result = await this._trpcClient.auth.passkeyLoginFinish.mutate({
+			response,
+			...refreshFlag(options)
+		});
 		if (typeof result === "object" && result !== null && "token" in result) {
 			const r = result;
 			const requiresSecondFactor = r.requiresTotp === true || Array.isArray(r.secondFactors) && r.secondFactors.length > 0;
@@ -1030,8 +1039,22 @@ var System = class {
 		}
 		return result;
 	}
-	async logout() {
-		await this._trpcClient.auth.logout.mutate();
+	/**
+	* Swap a refresh token for a new access token and a ROTATED refresh token
+	* (the old one stops working). Sets the new access token on this client.
+	* Throws a tRPC UNAUTHORIZED when the session is over — sign in again.
+	*/
+	async refreshSession(refreshToken) {
+		const result = await this._trpcClient.auth.refreshSession.mutate({ refreshToken });
+		this.setToken(result.token);
+		return result;
+	}
+	/**
+	* End this session on the hub (its tokens stop working at once);
+	* `everywhere: true` ends every session of the user.
+	*/
+	async logout(options = {}) {
+		await this._trpcClient.auth.logout.mutate(options.everywhere === true ? { everywhere: true } : void 0);
 	}
 	async getMe() {
 		return await this._trpcClient.auth.me.query();
@@ -1045,8 +1068,25 @@ var System = class {
 	async confirmOwnTotp(input) {
 		return await this._trpcClient.auth.confirmOwnTotp.mutate(input);
 	}
-	async disableOwnTotp() {
-		return await this._trpcClient.auth.disableOwnTotp.mutate();
+	/** Needs a fresh `reauthToken` from {@link reauthenticate}. */
+	async disableOwnTotp(input) {
+		return await this._trpcClient.auth.disableOwnTotp.mutate(input);
+	}
+	/**
+	* Re-authentication, passkey path step 1: assertion options for the
+	* caller's own passkeys. Feed `optionsJSON` to `startAuthentication`, then
+	* pass the result to {@link reauthenticate} as `passkeyResponse`.
+	*/
+	async reauthBeginPasskey() {
+		return await this._trpcClient.auth.reauthBeginPasskey.mutate();
+	}
+	/**
+	* Prove it is you — the current password or a passkey assertion — for a
+	* 5-minute `reauthToken`, required by `disableOwnTotp`, `removeOwnPasskey`
+	* and `auth.beginExternalLink` (valid only in this session).
+	*/
+	async reauthenticate(input) {
+		return await this._trpcClient.auth.reauthenticate.mutate(input);
 	}
 	async getOwnTotpStatus() {
 		return await this._trpcClient.auth.getOwnTotpStatus.query();
@@ -1060,6 +1100,7 @@ var System = class {
 	async listOwnPasskeys() {
 		return await this._trpcClient.auth.listOwnPasskeys.query();
 	}
+	/** Needs a fresh `reauthToken` from {@link reauthenticate}. */
 	async removeOwnPasskey(input) {
 		return await this._trpcClient.auth.removeOwnPasskey.mutate(input);
 	}
@@ -1409,6 +1450,119 @@ 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.
@@ -1721,4 +1875,4 @@ function getClassesForTimelinePreset(preset, customClasses) {
 	}
 }
 //#endregion
-export { DEFAULT_ENABLED_CLASSES, DetectionClass, System, TIMELINE_PRESET_ALL, TIMELINE_PRESET_CRITICAL, TIMELINE_PRESET_IMPORTANT, animalClasses, audioClasses, audioLabelClasses, createSystem, defaultDetectionClasses, detectionClassesDefaultMap, doorbellClasses, faceClasses, getClassesForTimelinePreset, getParentClass, getParentDetectionClass, isAnimalClassname, isAudioClassname, isDoorbellClassname, isFaceClassname, isLabelDetection, isMotionClassname, isPackageClassname, isPersonClassname, isPlateClassname, isSensorLabelClassname, isVehicleClassname, licensePlateClasses, motionClasses, packageClasses, personClasses, raceFastestEndpoint, sensorLabelClasses, vehicleClasses };
+export { DEFAULT_ENABLED_CLASSES, DetectionClass, SessionKeeper, System, TIMELINE_PRESET_ALL, TIMELINE_PRESET_CRITICAL, TIMELINE_PRESET_IMPORTANT, animalClasses, audioClasses, audioLabelClasses, createSystem, defaultDetectionClasses, detectionClassesDefaultMap, doorbellClasses, faceClasses, getClassesForTimelinePreset, getParentClass, getParentDetectionClass, isAnimalClassname, isAudioClassname, isDoorbellClassname, isFaceClassname, isLabelDetection, isMotionClassname, isPackageClassname, isPersonClassname, isPlateClassname, isSensorLabelClassname, isSessionRefusal, isVehicleClassname, jwtExpiresAt, licensePlateClasses, motionClasses, packageClasses, personClasses, raceFastestEndpoint, sensorLabelClasses, vehicleClasses };

package/dist/session-keeper.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Keeps a refreshing CamStack session alive without the user noticing.
+ *
+ * The hub hands a refreshing client a short access token (default 2 h) and a
+ * rotating refresh token. This schedules `auth.refreshSession` shortly before
+ * the access token expires, hands every rotated pair to the app to persist,
+ * and reports the end of the session only when the hub REFUSES the refresh —
+ * a network failure is retried, never treated as a sign-out.
+ *
+ * Transport-agnostic: the caller supplies `refresh` (normally
+ * `System.refreshSession`), so the keeper outlives a System that is rebuilt.
+ */
+export interface SessionTokens {
+    /** The access token (Bearer). */
+    readonly token: string;
+    /** The rotating refresh token, when the session is refreshable. */
+    readonly refreshToken?: string;
+    /** When the access token expires (epoch ms); decoded from the JWT when absent. */
+    readonly expiresAt?: number;
+}
+export interface SessionKeeperOptions {
+    /** Swap a refresh token for a new pair (`System.refreshSession`). */
+    readonly refresh: (refreshToken: string) => Promise<SessionTokens>;
+    /** Persist / apply a rotated pair (also called after `ensureFresh`). */
+    readonly onTokens: (tokens: SessionTokens) => void;
+    /** The hub refused the refresh: the session is over — sign the user out. */
+    readonly onExpired: () => void;
+    /** Refresh this long before the access token expires (default 5 min, at most half its life). */
+    readonly marginMs?: number;
+    readonly now?: () => number;
+    /** Timer hook (tests); returns a cancel function. */
+    readonly setTimer?: (fn: () => void, ms: number) => () => void;
+}
+/** Decode a JWT's `exp` (seconds) to epoch ms, or `null`. Never throws. */
+export declare function jwtExpiresAt(token: string): number | null;
+/** Is `error` the hub saying the session is over (as opposed to a transport failure)? */
+export declare function isSessionRefusal(error: unknown): boolean;
+export declare class SessionKeeper {
+    private readonly options;
+    private current;
+    private cancel;
+    private inflight;
+    private readonly now;
+    private readonly setTimer;
+    constructor(options: SessionKeeperOptions);
+    /** Take over `tokens` (a login, a restore from storage) and schedule its refresh. */
+    adopt(tokens: SessionTokens): void;
+    /** The tokens the keeper holds now. */
+    tokens(): SessionTokens | null;
+    /**
+     * 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.
+     */
+    ensureFresh(marginMs?: number): Promise<void>;
+    /** Refresh immediately. `null` when there is nothing to refresh or it failed. */
+    refreshNow(): Promise<SessionTokens | null>;
+    stop(): void;
+    private margin;
+    private expiresAtOf;
+    private schedule;
+    private arm;
+}

package/dist/system.d.ts

@@ -50,6 +50,38 @@ export interface SystemConfig {
     readonly maxRetryDelayMs?: number;
 }
 type ConnectionListener = (state: BackendConnectionState, version: number) => void;
+/** Options of every login leg. */
+export interface LoginOptions {
+    /** Ask for a short access token + a rotating refresh token (recommended). */
+    readonly refreshable?: boolean;
+}
+/** What a login leg returns: a session, or a second-factor challenge. */
+export interface LoginOutcome {
+    readonly token: string;
+    readonly requiresTotp?: boolean;
+    readonly secondFactors?: readonly SecondFactorKind[];
+    /** When the access token expires (epoch ms). */
+    readonly expiresAt?: number;
+    /** The server-side login session. */
+    readonly sessionId?: string;
+    /** When the session expires unless refreshed (epoch ms). */
+    readonly sessionExpiresAt?: number;
+    /** Only for `refreshable: true` — swap it at `refreshSession` before `expiresAt`. */
+    readonly refreshToken?: string;
+}
+/** What `refreshSession` returns. */
+export interface RefreshedSession {
+    readonly token: string;
+    readonly refreshToken: string;
+    readonly expiresAt: number;
+    readonly sessionId: string;
+    readonly sessionExpiresAt: number;
+    readonly user: {
+        readonly id: string;
+        readonly username: string;
+        readonly isAdmin: boolean;
+    };
+}
 export interface SystemLiveEvent<TData = unknown> {
     readonly id: string;
     readonly timestamp: Date | string;
@@ -207,11 +239,7 @@ export declare class System {
     /** Tear down WS connection + mirror. The instance is unusable afterwards. */
     close(): void;
     private disposeMirror;
-    login(username: string, password: string): Promise<{
-        token: string;
-        requiresTotp?: boolean;
-        secondFactors?: readonly SecondFactorKind[];
-    }>;
+    login(username: string, password: string, options?: LoginOptions): Promise<LoginOutcome>;
     /**
      * Second leg of the 2FA login. The caller passes the challenge
      * token returned by `login` (when `requiresTotp: true`) plus the
@@ -219,9 +247,7 @@ export declare class System {
      * server mints the real session JWT, which we set as the active
      * token on this client.
      */
-    loginVerifyTotp(challengeToken: string, code: string): Promise<{
-        token: string;
-    }>;
+    loginVerifyTotp(challengeToken: string, code: string, options?: LoginOptions): Promise<LoginOutcome>;
     /**
      * Passkey second leg — step 1. Exchanges the login challenge token for
      * the WebAuthn assertion options; the caller feeds `optionsJSON` to
@@ -235,9 +261,7 @@ export declare class System {
      * success the server mints the real session JWT, which we set as the
      * active token on this client.
      */
-    loginVerifyPasskey(challengeToken: string, response: Record<string, unknown>): Promise<{
-        token: string;
-    }>;
+    loginVerifyPasskey(challengeToken: string, response: Record<string, unknown>, options?: LoginOptions): Promise<LoginOutcome>;
     /**
      * Usernameless (passkey-FIRST) login — step 1. Fetches discoverable-
      * credential assertion options (EMPTY `allowCredentials`); the caller
@@ -259,12 +283,20 @@ export declare class System {
      * `secondFactors`. That token is NOT persisted as the active session
      * — the caller completes the remaining factor via `loginVerifyTotp`.
      */
-    passkeyLoginFinish(response: Record<string, unknown>): Promise<{
-        token: string;
-        requiresTotp?: boolean;
-        secondFactors?: readonly SecondFactorKind[];
-    }>;
-    logout(): Promise<void>;
+    passkeyLoginFinish(response: Record<string, unknown>, options?: LoginOptions): Promise<LoginOutcome>;
+    /**
+     * Swap a refresh token for a new access token and a ROTATED refresh token
+     * (the old one stops working). Sets the new access token on this client.
+     * Throws a tRPC UNAUTHORIZED when the session is over — sign in again.
+     */
+    refreshSession(refreshToken: string): Promise<RefreshedSession>;
+    /**
+     * End this session on the hub (its tokens stop working at once);
+     * `everywhere: true` ends every session of the user.
+     */
+    logout(options?: {
+        readonly everywhere?: boolean;
+    }): Promise<void>;
     getMe(): Promise<UserInfo>;
     changeOwnPassword(input: {
         currentPassword: string;
@@ -281,9 +313,34 @@ export declare class System {
     }): Promise<{
         success: true;
     }>;
-    disableOwnTotp(): Promise<{
+    /** Needs a fresh `reauthToken` from {@link reauthenticate}. */
+    disableOwnTotp(input: {
+        reauthToken: string;
+    }): Promise<{
         success: true;
     }>;
+    /**
+     * Re-authentication, passkey path step 1: assertion options for the
+     * caller's own passkeys. Feed `optionsJSON` to `startAuthentication`, then
+     * pass the result to {@link reauthenticate} as `passkeyResponse`.
+     */
+    reauthBeginPasskey(): Promise<{
+        optionsJSON: Record<string, unknown>;
+    }>;
+    /**
+     * Prove it is you — the current password or a passkey assertion — for a
+     * 5-minute `reauthToken`, required by `disableOwnTotp`, `removeOwnPasskey`
+     * and `auth.beginExternalLink` (valid only in this session).
+     */
+    reauthenticate(input: {
+        readonly password: string;
+    } | {
+        readonly passkeyResponse: Record<string, unknown>;
+    }): Promise<{
+        reauthToken: string;
+        expiresAt: number;
+        method: 'password' | 'passkey';
+    }>;
     getOwnTotpStatus(): Promise<{
         enabled: boolean;
         confirmedAt: number | null;
@@ -299,8 +356,10 @@ export declare class System {
         credentialId: string;
     }>;
     listOwnPasskeys(): Promise<readonly PasskeySummary[]>;
+    /** Needs a fresh `reauthToken` from {@link reauthenticate}. */
     removeOwnPasskey(input: {
         credentialId: string;
+        reauthToken: string;
     }): Promise<{
         success: true;
     }>;

package/package.json

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