@thunderid/browser 1.3.0 → 1.4.0

package/dist/cjs/index.cjs

@@ -35,18 +35,226 @@ fast_sha256 = __toESM(fast_sha256);
 let jose = require("jose");
 jose = __toESM(jose);
 
-//#region src/constants/SPAConstants.ts
-const ERROR = "error";
-const ERROR_DESCRIPTION = "error_description";
-const CUSTOM_GRANT_CONFIG = "custom_grant_config";
-const STATE_QUERY = "state";
-const SILENT_SIGN_IN_STATE = "sign-in-silently";
-const SILENT_SIGN_IN_TIMEOUT = 1e4;
-const ACCESS_TOKEN_INVALID = "Access token is invalid";
-const REFRESH_ACCESS_TOKEN_ERR0R = "refresh-access-token-error";
-const TOKEN_REQUEST_CONFIG_KEY = "token_request_config";
-const SILENT_SIGN_IN_SIGNED_IN = "silent_sign_in_signed_in";
-const SILENT_SIGN_IN_SIGNED_OUT = "silent_sign_in_signed_out";
+//#region src/BackendClient.ts
+/**
+* Header every backend request carries. A cross-origin page cannot set it without a CORS preflight,
+* which the backend never answers, so it keeps the cookie from being used cross-site.
+*/
+const BACKEND_REQUEST_HEADER = "X-Requested-With";
+const BACKEND_REQUEST_HEADER_VALUE = "XMLHttpRequest";
+/** A check on focus is skipped when the last one is more recent than this, in milliseconds. */
+const FOCUS_CHECK_THROTTLE = 5e3;
+/**
+* Talks to the app's backend when sign-in runs there: reads the session, refreshes it, and starts and ends it. The
+* browser never holds a token; the backend keeps them behind an `HttpOnly` cookie.
+*/
+var BackendClient = class BackendClient {
+	session;
+	refreshing;
+	hasLoadedSession = false;
+	/** Whether the session last seen was signed in, so a later read can tell it has ended. */
+	wasSignedIn = false;
+	lastCheck = 0;
+	signedOutListeners = [];
+	constructor(endpoints) {
+		this.endpoints = endpoints;
+	}
+	/**
+	* Calls the listener when a signed-in session turns out to have ended without this client signing
+	* out: another app signed the user out, an administrator ended the session, or it timed out.
+	*/
+	onSignedOut(listener) {
+		this.signedOutListeners.push(listener);
+	}
+	/**
+	* Records that the session has ended, and tells the listeners when it had been signed in.
+	*/
+	markSignedOut() {
+		this.session = Promise.resolve({ isSignedIn: false });
+		this.hasLoadedSession = true;
+		if (this.wasSignedIn) {
+			this.wasSignedIn = false;
+			this.signedOutListeners.forEach((listener) => listener());
+		}
+	}
+	/**
+	* Asks the backend whether the session is still live. The check neither refreshes the session nor
+	* counts as activity, so it can be polled without keeping an idle session alive.
+	*
+	* @returns Whether the session is live. A failed check reports the last known state.
+	*/
+	async checkSession() {
+		this.lastCheck = Date.now();
+		try {
+			const response = await this.send(this.endpoints.checkSession, "GET");
+			if (!response.ok) return this.wasSignedIn;
+			const { isSignedIn } = await response.json();
+			if (!isSignedIn) this.markSignedOut();
+			return isSignedIn;
+		} catch {
+			return this.wasSignedIn;
+		}
+	}
+	/**
+	* Watches for the session ending while the page is open: checks it whenever the page gets focus or
+	* becomes visible again, and every `pollSeconds` while it is visible when that is positive.
+	*
+	* @returns A function that stops watching.
+	*/
+	watch(pollSeconds) {
+		const checkIfSignedIn = () => {
+			if (this.wasSignedIn && document.visibilityState === "visible") this.checkSession();
+		};
+		const onFocus = () => {
+			if (Date.now() - this.lastCheck >= FOCUS_CHECK_THROTTLE) checkIfSignedIn();
+		};
+		document.addEventListener("visibilitychange", onFocus);
+		window.addEventListener("focus", onFocus);
+		const timer = pollSeconds > 0 ? setInterval(checkIfSignedIn, pollSeconds * 1e3) : void 0;
+		return () => {
+			document.removeEventListener("visibilitychange", onFocus);
+			window.removeEventListener("focus", onFocus);
+			if (timer) clearInterval(timer);
+		};
+	}
+	/**
+	* Returns the session. The result is cached until a sign-in, sign-out, or refresh changes it, so
+	* repeated sign-in checks do not reach the server each time.
+	*
+	* @param reload - Read the session from the server even when one is cached.
+	*/
+	getSession(reload = false) {
+		if (reload) this.session = void 0;
+		this.session ??= this.loadSession().catch((error) => {
+			this.session = void 0;
+			throw error;
+		}).finally(() => {
+			this.hasLoadedSession = true;
+		});
+		return this.session;
+	}
+	/**
+	* Whether this client talks to exactly these endpoints.
+	*/
+	hasEndpoints(endpoints) {
+		return Object.keys(endpoints).every((key) => key === "bypass" ? JSON.stringify(this.endpoints.bypass) === JSON.stringify(endpoints.bypass) : this.endpoints[key] === endpoints[key]);
+	}
+	/**
+	* Whether the first session read is still in flight, so it is not yet known whether the user is
+	* signed in.
+	*/
+	isLoading() {
+		return !this.hasLoadedSession;
+	}
+	/**
+	* Refreshes the session once, sharing one request between concurrent callers.
+	*
+	* @returns Whether the session was refreshed. When it was not, the session is now signed out.
+	*/
+	refresh() {
+		this.refreshing ??= this.send(this.endpoints.refresh, "POST").then((response) => {
+			if (response.ok) this.session = void 0;
+			else this.markSignedOut();
+			return response.ok;
+		}).finally(() => {
+			this.refreshing = void 0;
+		});
+		return this.refreshing;
+	}
+	/**
+	* The URL that starts sign-in at the backend and comes back to `returnTo`.
+	*/
+	getSignInUrl(returnTo) {
+		return `${this.endpoints.signIn}?${new URLSearchParams({ returnTo }).toString()}`;
+	}
+	/**
+	* Ends the backend session.
+	*
+	* @returns The URL the browser visits to end the session at the authorization server.
+	*/
+	async signOut() {
+		const response = await this.send(this.endpoints.signOut, "POST");
+		this.wasSignedIn = false;
+		this.session = Promise.resolve({ isSignedIn: false });
+		if (!response.ok) throw new __thunderid_javascript.ThunderIDAuthException("SPA-BACKEND_CLIENT-SO-SE01", "Sign out failed.", `The backend sign-out endpoint returned ${response.status}.`);
+		return (await response.json()).redirectUrl;
+	}
+	/**
+	* Maps an API URL to its backend proxy URL.
+	*
+	* @returns The proxy URL, or `undefined` when the URL is not under the API base and so cannot be
+	* sent with the session's credentials.
+	*/
+	toProxyUrl(url) {
+		const { apiBaseUrl, proxy } = this.endpoints;
+		let rest;
+		if (url === apiBaseUrl || url.startsWith(`${apiBaseUrl}/`) || url.startsWith(`${apiBaseUrl}?`)) rest = url.slice(apiBaseUrl.length);
+		else if (url.startsWith("/") && !url.startsWith("//")) rest = url;
+		else return;
+		return `${proxy}${rest.startsWith("/") ? rest : `/${rest}`}`;
+	}
+	/**
+	* Whether a request to this URL skips the proxy and goes straight from the browser.
+	*/
+	isBypassed(url) {
+		return this.endpoints.bypass.urls.some((base) => url === base || url.startsWith(`${base}/`) || url.startsWith(`${base}?`));
+	}
+	/**
+	* Whether requests that skip the proxy carry the access token.
+	*/
+	attachesTokenOnBypass() {
+		return this.endpoints.bypass.attachToken;
+	}
+	/**
+	* Gets an access token for the requests that skip the proxy from the backend's token endpoint. It comes without a
+	* refresh token: when it expires, the caller asks again.
+	*
+	* @returns The token response, as the backend sent it.
+	*/
+	async requestAccessToken() {
+		let response = await this.send(this.endpoints.token, "POST");
+		if (response.status === 401) {
+			const { error } = await response.json().catch(() => ({}));
+			if (error === "session_expired" && await this.refresh()) response = await this.send(this.endpoints.token, "POST");
+			else if (error === "login_required") this.markSignedOut();
+		}
+		if (!response.ok) throw new __thunderid_javascript.ThunderIDAuthException("SPA-BACKEND_CLIENT-RAT-SE01", "Failed to get an access token.", `The backend token endpoint returned ${response.status}.`);
+		return await response.json();
+	}
+	/**
+	* The headers and credentials mode every backend request is sent with.
+	*/
+	static requestInit(headers = {}) {
+		return {
+			credentials: "same-origin",
+			headers: {
+				...headers,
+				[BACKEND_REQUEST_HEADER]: BACKEND_REQUEST_HEADER_VALUE
+			}
+		};
+	}
+	async loadSession() {
+		let response = await this.send(this.endpoints.session, "GET");
+		if (response.status === 401 && await this.refresh()) response = await this.send(this.endpoints.session, "GET");
+		if (response.status === 401) return this.signedOutSession();
+		if (!response.ok) throw new __thunderid_javascript.ThunderIDAuthException("SPA-BACKEND_CLIENT-GS-SE01", "Failed to read the session.", `The backend session endpoint returned ${response.status}.`);
+		const session = await response.json();
+		if (!session.isSignedIn) return this.signedOutSession();
+		this.wasSignedIn = true;
+		return session;
+	}
+	signedOutSession() {
+		if (this.wasSignedIn) queueMicrotask(() => this.markSignedOut());
+		return { isSignedIn: false };
+	}
+	send(url, method) {
+		return fetch(url, {
+			method,
+			...BackendClient.requestInit({ Accept: "application/json" })
+		});
+	}
+};
+var BackendClient_default = BackendClient;
 
 //#endregion
 //#region src/FetchHttpClient.ts
@@ -64,6 +272,9 @@ var FetchHttpClient = class FetchHttpClient extends __thunderid_javascript.HttpC
 		if (!this.instances.has(instanceId)) this.instances.set(instanceId, new FetchHttpClient(isHandlerEnabled, attachToken));
 		return this.instances.get(instanceId);
 	}
+	static setInstance(instanceId, client) {
+		this.instances.set(instanceId, client);
+	}
 	static destroyInstance(instanceId = 0) {
 		this.instances.delete(instanceId);
 	}
@@ -123,6 +334,108 @@ var FetchHttpClient = class FetchHttpClient extends __thunderid_javascript.HttpC
 };
 var FetchHttpClient_default = FetchHttpClient;
 
+//#endregion
+//#region src/BackendHttpClient.ts
+/**
+* The HTTP client used when sign-in runs on the backend. It sends each request through the backend's
+* API proxy with the session cookie instead of attaching a token, and refreshes the session once
+* when the backend reports
+* it expired. Requests under `bypass` go straight there with the cookies and, unless turned off, the
+* access token the backend issued.
+*/
+const hasBackendError = (error, code$1) => error?.response?.status === 401 && error.response.data?.error === code$1;
+const isSessionExpired = (error) => hasBackendError(error, "session_expired");
+var BackendHttpClient = class extends FetchHttpClient_default {
+	/**
+	* @param backend - The backend client.
+	* @param getAccessToken - Returns the access token for bypassed requests; `renew` asks for a new one.
+	*/
+	constructor(backend, getAccessToken) {
+		super(true);
+		this.backend = backend;
+		this.getAccessToken = getAccessToken;
+	}
+	async transport(config) {
+		if (this.backend.isBypassed(config.url ?? "")) return this.sendBypassed(config);
+		const proxyUrl = this.backend.toProxyUrl(config.url ?? "");
+		if (!proxyUrl) throw Object.assign(/* @__PURE__ */ new Error(`"${config.url}" is not under the backend API base, so it cannot be sent.`), {
+			code: "BACKEND_UNSUPPORTED_URL",
+			config
+		});
+		const send = () => super.transport({
+			...config,
+			...BackendClient_default.requestInit(config.headers),
+			url: proxyUrl
+		});
+		try {
+			return await send();
+		} catch (error) {
+			if (isSessionExpired(error) && await this.backend.refresh()) return send();
+			if (hasBackendError(error, "login_required")) this.backend.markSignedOut();
+			throw error;
+		}
+	}
+	/**
+	* Sends a request straight to its URL, skipping the proxy, with the cookies and the access token.
+	* When the API rejects the token, it gets a new one and retries once.
+	*/
+	async sendBypassed(config) {
+		if (!this.backend.attachesTokenOnBypass()) return super.transport({
+			...config,
+			credentials: "include"
+		});
+		const send = async (renew) => super.transport({
+			...config,
+			credentials: "include",
+			headers: {
+				...config.headers,
+				Authorization: `Bearer ${await this.getAccessToken(renew)}`
+			}
+		});
+		try {
+			return await send(false);
+		} catch (error) {
+			if (error.response?.status === 401) return send(true);
+			throw error;
+		}
+	}
+};
+var BackendHttpClient_default = BackendHttpClient;
+
+//#endregion
+//#region src/constants/Hooks.ts
+/**
+* Event hook names for attaching callbacks via `ThunderIDBrowserClient.on()`.
+*/
+let Hooks = /* @__PURE__ */ function(Hooks$1) {
+	Hooks$1["SignIn"] = "sign-in";
+	Hooks$1["SignOut"] = "sign-out";
+	Hooks$1["Initialize"] = "initialize";
+	Hooks$1["HttpRequestStart"] = "http-request-start";
+	Hooks$1["HttpRequestFinish"] = "http-request-finish";
+	Hooks$1["HttpRequestError"] = "http-request-error";
+	Hooks$1["HttpRequestSuccess"] = "http-request-success";
+	Hooks$1["RevokeAccessToken"] = "revoke-access-token";
+	Hooks$1["CustomGrant"] = "custom-grant";
+	Hooks$1["SignOutFailed"] = "sign-out-failed";
+	return Hooks$1;
+}({});
+var Hooks_default = Hooks;
+
+//#endregion
+//#region src/constants/SPAConstants.ts
+const ERROR = "error";
+const ERROR_DESCRIPTION = "error_description";
+const CUSTOM_GRANT_CONFIG = "custom_grant_config";
+const STATE_QUERY = "state";
+const SILENT_SIGN_IN_STATE = "sign-in-silently";
+const SILENT_SIGN_IN_TIMEOUT = 1e4;
+const ACCESS_TOKEN_INVALID = "Access token is invalid";
+const REFRESH_ACCESS_TOKEN_ERR0R = "refresh-access-token-error";
+const TOKEN_REQUEST_CONFIG_KEY = "token_request_config";
+const SILENT_SIGN_IN_SIGNED_IN = "silent_sign_in_signed_in";
+const SILENT_SIGN_IN_SIGNED_OUT = "silent_sign_in_signed_out";
+
 //#endregion
 //#region src/models/BrowserStorage.ts
 /**
@@ -782,6 +1095,57 @@ var AuthenticationHelper = class {
 };
 var AuthenticationHelper_default = AuthenticationHelper;
 
+//#endregion
+//#region src/utils/createHttpClientFetcher.ts
+/**
+* Builds a `fetch`-shaped function backed by the shared `FetchHttpClient` singleton, for
+* framework wrappers (`@thunderid/react`, `@thunderid/vue`) that need to hand a core
+* `@thunderid/javascript` API function a `fetcher` carrying the access token automatically.
+*
+* Unlike a plain `fetch` call, `FetchHttpClient.request` throws on a non-2xx response instead
+* of resolving it. This adapter catches that and reconstructs a `Response`-shaped object from
+* the thrown error's `response`, so the core API function sees the real status and body instead
+* of treating every non-2xx result as a network failure. A genuine network error (no response
+* attached) still propagates.
+*
+* @param instanceId - Which `FetchHttpClient` instance to use, for multi-instance apps. Defaults to `0`.
+* @returns A function matching the `(url, config) => Promise<Response>` shape core API functions expect.
+* @example
+* ```typescript
+* await updateMeCredentials({
+*   ...config,
+*   fetcher: fetcher ?? createHttpClientFetcher(instanceId),
+* });
+* ```
+*/
+const createHttpClientFetcher = (instanceId = 0) => {
+	return async (url, config) => {
+		const httpClient = FetchHttpClient_default.getInstance(instanceId);
+		const toResponse = (data, status, statusText) => ({
+			json: () => Promise.resolve(data),
+			ok: status >= 200 && status < 300,
+			status,
+			statusText,
+			text: () => Promise.resolve(typeof data === "string" ? data : JSON.stringify(data))
+		});
+		try {
+			const response = await httpClient.request({
+				data: config.body ? JSON.parse(config.body) : void 0,
+				headers: config.headers,
+				method: config.method || "POST",
+				signal: config.signal,
+				url
+			});
+			return toResponse(response.data, response.status, response.statusText || "");
+		} catch (error) {
+			const httpError = error;
+			if (httpError?.response) return toResponse(httpError.response.data, httpError.response.status, httpError.response.statusText ?? "");
+			throw error;
+		}
+	};
+};
+var createHttpClientFetcher_default = createHttpClientFetcher;
+
 //#endregion
 //#region src/utils/navigate.ts
 /**
@@ -2441,16 +2805,12 @@ var ThunderIDBrowserClient = class ThunderIDBrowserClient extends __thunderid_ja
 	_storage = BrowserStorage_default.SessionStorage;
 	_getSignOutURLFromSessionStorage = false;
 	_isHttpHandlerEnabled = true;
-	_httpErrorCallback;
-	_httpFinishCallback;
-	_onSignInCallback = () => null;
-	_onSignOutCallback = () => null;
-	_onSignOutFailedCallback = () => null;
-	_onEndUserSession = () => null;
-	_onInitialize = () => null;
-	_onCustomGrant = /* @__PURE__ */ new Map();
+	_hookCallbacks = /* @__PURE__ */ new Map();
 	_initialized = false;
 	_startedInitialize = false;
+	_backend;
+	_stopBackendWatch;
+	_backendTokenRequest;
 	constructor(instanceId = 0) {
 		super(void 0, new SPACryptoUtils_default());
 		this._browserInstanceId = instanceId;
@@ -2474,7 +2834,35 @@ var ThunderIDBrowserClient = class ThunderIDBrowserClient extends __thunderid_ja
 		const attachToken = async (request) => {
 			await this._authHelper?.attachTokenToRequestConfig(request);
 		};
-		this._httpClient = FetchHttpClient_default.getInstance(this._browserInstanceId, true, attachToken);
+		const backendEndpoints = (0, __thunderid_javascript.resolveBackendEndpoints)(merged, window.location.origin);
+		if (backendEndpoints) {
+			if (!this._backend?.hasEndpoints(backendEndpoints)) {
+				this._backend = new BackendClient_default(backendEndpoints);
+				this._backend.onSignedOut(() => {
+					this.getStorageManager().removeSessionData();
+					this._emitHook(Hooks_default.SignOut);
+				});
+			}
+			this._stopBackendWatch?.();
+			const { session } = merged;
+			this._stopBackendWatch = this._backend.watch(Number(session?.checkInterval ?? 0));
+			this._httpClient = new BackendHttpClient_default(this._backend, (renew) => this._getBackendAccessToken(renew));
+			FetchHttpClient_default.setInstance(this._browserInstanceId, this._httpClient);
+			this._backend.getSession().catch((error) => {
+				logger$2.debug("Could not read the backend session.", error);
+			});
+		} else {
+			this._stopBackendWatch?.();
+			this._stopBackendWatch = void 0;
+			this._backend = void 0;
+			this._httpClient = FetchHttpClient_default.getInstance(this._browserInstanceId, true, attachToken);
+		}
+		this._httpClient.setHttpRequestStartCallback((request) => {
+			this._emitHook(Hooks_default.HttpRequestStart, request);
+		});
+		this._httpClient.setHttpRequestSuccessCallback((response) => {
+			this._emitHook(Hooks_default.HttpRequestSuccess, response);
+		});
 		this._authHelper = new AuthenticationHelper_default(sm, this._spaHelper, this._browserInstanceId, {
 			exchangeToken: (cfg) => super.exchangeToken(cfg),
 			getAccessToken: (sessionId) => this.getAccessToken(sessionId),
@@ -2489,7 +2877,7 @@ var ThunderIDBrowserClient = class ThunderIDBrowserClient extends __thunderid_ja
 			setPKCECode: (pkceKey, state) => this.setPKCECode(pkceKey, state)
 		});
 		this._initialized = true;
-		if (this._onInitialize) this._onInitialize(true);
+		this._emitHook(Hooks_default.Initialize, true);
 		if (!merged.autoLogoutOnTokenRefreshError) return true;
 		window.addEventListener("message", (event) => {
 			if (event?.data?.type === REFRESH_ACCESS_TOKEN_ERR0R) this.signOut();
@@ -2513,14 +2901,29 @@ var ThunderIDBrowserClient = class ThunderIDBrowserClient extends __thunderid_ja
 		return true;
 	}
 	isLoading() {
-		return false;
+		return this._backend?.isLoading() ?? false;
+	}
+	/**
+	* Whether sign-in runs on the app's backend, which holds the tokens so the browser never does.
+	*/
+	isBackendMode() {
+		return this._backend !== void 0;
+	}
+	_rejectInBackendMode(operation) {
+		return Promise.reject(new __thunderid_javascript.ThunderIDAuthException("SPA-AUTH_CLIENT-BACKEND-NS01", "Not supported when sign-in runs on the backend.", `${operation} is not available when sign-in runs on the backend, because the browser holds no tokens.`));
 	}
 	async signIn(config, authorizationCode, state, tokenRequestConfig) {
 		await this.isInitialized();
+		if (this._backend) {
+			if (config?.callOnlyOnRedirect) return;
+			location.href = this._backend.getSignInUrl(`${window.location.pathname}${window.location.search}`);
+			await SPAUtils_default.waitTillPageRedirect();
+			return;
+		}
 		if (!SPAUtils_default.canContinueSignIn(Boolean(config?.callOnlyOnRedirect), authorizationCode)) return;
 		delete config?.callOnlyOnRedirect;
 		const user = await this._signInInternal(config, authorizationCode, state, tokenRequestConfig);
-		if (user && this._onSignInCallback) this._onSignInCallback(user);
+		if (user) this._emitHook(Hooks_default.SignIn, user);
 		return user;
 	}
 	async _signInInternal(signInConfig, authorizationCode, state, tokenRequestConfig) {
@@ -2587,9 +2990,10 @@ var ThunderIDBrowserClient = class ThunderIDBrowserClient extends __thunderid_ja
 	}
 	async signInSilently(additionalParams, tokenRequestConfig) {
 		await this.isInitialized();
+		if (this._backend) return await this.isSignedIn() ? this.getUser() : false;
 		if (SPAUtils_default.wasSignInCalled()) return;
 		const response = await this._signInSilentlyInternal(additionalParams, tokenRequestConfig);
-		if (this._onSignInCallback && response) this._onSignInCallback(response);
+		if (response) this._emitHook(Hooks_default.SignIn, response);
 		return response;
 	}
 	async _signInSilentlyInternal(additionalParams, tokenRequestConfig) {
@@ -2604,6 +3008,14 @@ var ThunderIDBrowserClient = class ThunderIDBrowserClient extends __thunderid_ja
 			sessionId = sessionIdOrAfterSignOut;
 			afterSignOut = afterSignOutParam;
 		}
+		if (this._backend) {
+			await this.getStorageManager().removeSessionData();
+			const backendSignOutUrl = await this._backend.signOut();
+			afterSignOut?.(backendSignOutUrl);
+			location.href = backendSignOutUrl;
+			await SPAUtils_default.waitTillPageRedirect();
+			return backendSignOutUrl;
+		}
 		const config = await this.getStorageManager().getConfigData();
 		let signOutUrl = "";
 		if (config?.rpInitiatedLogout !== false) {
@@ -2635,24 +3047,86 @@ var ThunderIDBrowserClient = class ThunderIDBrowserClient extends __thunderid_ja
 	}
 	async httpRequest(requestConfig) {
 		await this._validateMethod(false);
-		return this._authHelper.httpRequest(this._httpClient, requestConfig, this._isHttpHandlerEnabled, this._httpErrorCallback, this._httpFinishCallback);
+		if (this._backend) return this._backendRequest(requestConfig);
+		const response = await this._authHelper.httpRequest(this._httpClient, requestConfig, this._isHttpHandlerEnabled, this._emitHttpError, this._emitHttpFinish);
+		if (this._isHttpHandlerEnabled) this._emitHttpFinish();
+		return response;
 	}
 	async httpRequestAll(configs) {
 		await this._validateMethod(false);
-		return this._authHelper.httpRequestAll(configs, this._httpClient, this._isHttpHandlerEnabled, this._httpErrorCallback, this._httpFinishCallback);
+		if (this._backend) return Promise.all(configs.map((requestConfig) => this._backendRequest(requestConfig)));
+		const responses = await this._authHelper.httpRequestAll(configs, this._httpClient, this._isHttpHandlerEnabled, this._emitHttpError, this._emitHttpFinish);
+		if (this._isHttpHandlerEnabled) this._emitHttpFinish();
+		return responses;
+	}
+	async _backendRequest(requestConfig) {
+		try {
+			return await this._httpClient.request(requestConfig);
+		} catch (error) {
+			if (this._isHttpHandlerEnabled) await this._emitHttpError(error);
+			throw error;
+		} finally {
+			if (this._isHttpHandlerEnabled) this._emitHttpFinish();
+		}
 	}
 	async getUser(userId) {
 		await this._validateMethod();
+		if (this._backend) return (await this._backend.getSession()).user ?? {};
 		return super.getUser(userId);
 	}
+	/**
+	* Fetches the signed-in user's profile from the `/users/me` endpoint (or `endpoints.usersMe` when
+	* configured), sending the request through the client's HTTP client so the access token is attached.
+	*
+	* @param options - Optional `baseUrl` or full `url` overrides for the profile endpoint.
+	* @returns The user's profile.
+	*/
+	async getUserProfile(options) {
+		await this._validateMethod();
+		const configData = await this.getStorageManager().getConfigData();
+		const profile = await (0, __thunderid_javascript.getUsersMe)({
+			baseUrl: options?.baseUrl ?? configData?.baseUrl,
+			fetcher: createHttpClientFetcher_default(this._browserInstanceId),
+			url: (0, __thunderid_javascript.resolveResourceEndpoint)("usersMe", configData, options?.url)
+		});
+		return {
+			flattenedProfile: (0, __thunderid_javascript.generateFlattenedUserProfile)(profile),
+			profile
+		};
+	}
 	async getAccessToken(sessionId) {
+		if (this._backend) return this._getBackendAccessToken();
 		return super.getAccessToken(sessionId);
 	}
+	/**
+	* The access token for requests under `endpoints.backend.bypass`. Like a client credentials token it
+	* has no refresh token: it is kept in the session storage until it nears expiry, then requested again.
+	*
+	* @param renew - Request a new token even when the stored one is still valid.
+	*/
+	async _getBackendAccessToken(renew = false) {
+		const storageManager = this.getStorageManager();
+		const session = await storageManager.getSessionData();
+		const expiresAt = (session?.created_at ?? 0) + Number(session?.expires_in ?? 0) * 1e3;
+		if (!renew && session?.access_token && expiresAt - __thunderid_javascript.TokenConstants.Lifecycle.CLIENT_CREDENTIALS_REFRESH_MARGIN_MS > Date.now()) return session.access_token;
+		this._backendTokenRequest ??= this._backend.requestAccessToken().then(async (response) => {
+			await storageManager.setSessionData({
+				...response,
+				created_at: Date.now()
+			});
+			return response.access_token ?? "";
+		}).finally(() => {
+			this._backendTokenRequest = void 0;
+		});
+		return this._backendTokenRequest;
+	}
 	async getDecodedIdToken(userId, idToken) {
 		await this._validateMethod();
+		if (this._backend) return (await this._backend.getSession()).user ?? {};
 		return super.getDecodedIdToken(userId, idToken);
 	}
 	async getIdToken(userId) {
+		if (this._backend) return this._rejectInBackendMode("getIdToken");
 		await this._validateMethod();
 		return super.getIdToken(userId);
 	}
@@ -2670,17 +3144,23 @@ var ThunderIDBrowserClient = class ThunderIDBrowserClient extends __thunderid_ja
 	}
 	async isSignedIn(userId) {
 		await this.isInitialized();
+		if (this._backend) return (await this._backend.getSession()).isSignedIn;
 		return super.isSignedIn(userId);
 	}
 	notifySignIn(user) {
-		this._onSignInCallback(user);
+		this._emitHook(Hooks_default.SignIn, user);
 	}
 	async isSessionActive() {
 		await this.isInitialized();
+		if (this._backend) return this.isSignedIn();
 		return await this.getStorageManager().getSessionStatus() === "true";
 	}
 	async refreshAccessToken(userId) {
 		await this._validateMethod(false);
+		if (this._backend) {
+			if (!await this._backend.refresh()) return Promise.reject(new __thunderid_javascript.ThunderIDAuthException("SPA-AUTH_CLIENT-BACKEND-RF01", "Refresh failed.", "The backend could not refresh the session."));
+			return this.getUser();
+		}
 		try {
 			return await this._authHelper.refreshAccessToken((cfg) => this._enableRetrievingSignOutURLFromSession(cfg));
 		} catch (error) {
@@ -2688,18 +3168,20 @@ var ThunderIDBrowserClient = class ThunderIDBrowserClient extends __thunderid_ja
 		}
 	}
 	async revokeAccessToken(userId) {
+		if (this._backend) return this._rejectInBackendMode("revokeAccessToken");
 		await this._validateMethod();
 		const timer = await this._spaHelper.getRefreshTimeoutTimer();
 		await super.revokeAccessToken(userId);
 		await this._spaHelper.clearRefreshTokenTimeout(timer);
-		this._onEndUserSession && await this._onEndUserSession(true);
+		await this._emitHook(Hooks_default.RevokeAccessToken, true);
 		return true;
 	}
 	async exchangeToken(config) {
+		if (this._backend) return this._rejectInBackendMode("exchangeToken");
 		if (config.signInRequired) await this._validateMethod();
 		if (!config.id) return Promise.reject(new __thunderid_javascript.ThunderIDAuthException("SPA-AUTH_CLIENT-RCG-NF01", "The custom grant request id not found.", "Set the `id` attribute on the token exchange config."));
 		const response = await this._authHelper.exchangeToken(config, (cfg) => this._enableRetrievingSignOutURLFromSession(cfg));
-		this._onCustomGrant.get(config.id)?.(response);
+		this._emitHook(`${Hooks_default.CustomGrant}:${config.id}`, response);
 		return response;
 	}
 	async reInitialize(config) {
@@ -2708,6 +3190,7 @@ var ThunderIDBrowserClient = class ThunderIDBrowserClient extends __thunderid_ja
 	}
 	async startAutoRefreshToken() {
 		await this.isInitialized();
+		if (this._backend) return;
 		await this._spaHelper.clearRefreshTokenTimeout();
 		await this._spaHelper.refreshAccessTokenAutomatically(() => this.refreshAccessToken());
 	}
@@ -2726,47 +3209,57 @@ var ThunderIDBrowserClient = class ThunderIDBrowserClient extends __thunderid_ja
 	async decodeJwtToken(token) {
 		return this.getCryptoHelper().decodeJwtToken(token);
 	}
+	/**
+	* Subscribes a callback to a lifecycle hook. Every callback registered for a hook is called when it
+	* fires; registering the same callback again for the same hook has no further effect. Hooks can be
+	* registered before or after `initialize()`.
+	*
+	* @param hook - The hook to subscribe to (see `Hooks`).
+	* @param callback - Called when the hook fires.
+	* @param id - The custom grant id. Required for `custom-grant`.
+	*/
 	async on(hook, callback, id) {
 		await this.isInitialized();
 		if (!callback || typeof callback !== "function") throw new __thunderid_javascript.ThunderIDAuthException("SPA-AUTH_CLIENT-ON-IV02", "Invalid callback function.", "The provided callback must be a function.");
 		switch (hook) {
-			case "sign-in":
-				this._onSignInCallback = callback;
-				break;
-			case "sign-out":
-				this._onSignOutCallback = callback;
-				if (await SPAUtils_default.isSignOutSuccessful(ThunderIDBrowserClient.isSignOutSuccessful.bind(ThunderIDBrowserClient), () => ThunderIDBrowserClient.clearSession())) this._onSignOutCallback();
-				break;
-			case "revoke-access-token":
-				this._onEndUserSession = callback;
-				break;
-			case "initialize":
-				this._onInitialize = callback;
-				break;
-			case "http-request-error":
-				this._httpErrorCallback = callback;
-				break;
-			case "http-request-finish":
-				this._httpFinishCallback = callback;
+			case Hooks_default.SignIn:
+			case Hooks_default.RevokeAccessToken:
+			case Hooks_default.Initialize:
+			case Hooks_default.HttpRequestError:
+			case Hooks_default.HttpRequestFinish:
+			case Hooks_default.HttpRequestStart:
+			case Hooks_default.HttpRequestSuccess:
+				this._addHookCallback(hook, callback);
 				break;
-			case "http-request-start":
-				this._httpClient?.setHttpRequestStartCallback?.(callback);
+			case Hooks_default.SignOut:
+				this._addHookCallback(hook, callback);
+				if (await SPAUtils_default.isSignOutSuccessful(ThunderIDBrowserClient.isSignOutSuccessful.bind(ThunderIDBrowserClient), () => ThunderIDBrowserClient.clearSession())) callback();
 				break;
-			case "http-request-success":
-				this._httpClient?.setHttpRequestSuccessCallback?.(callback);
+			case Hooks_default.CustomGrant:
+				id && this._addHookCallback(`${Hooks_default.CustomGrant}:${id}`, callback);
 				break;
-			case "custom-grant":
-				id && this._onCustomGrant.set(id, callback);
-				break;
-			case "sign-out-failed": {
-				this._onSignOutFailedCallback = callback;
+			case Hooks_default.SignOutFailed: {
 				const signOutFail = SPAUtils_default.didSignOutFail(ThunderIDBrowserClient.didSignOutFail.bind(ThunderIDBrowserClient));
-				if (signOutFail) this._onSignOutFailedCallback(signOutFail);
+				if (signOutFail) callback(signOutFail);
 				break;
 			}
 			default: throw new __thunderid_javascript.ThunderIDAuthException("SPA-AUTH_CLIENT-ON-IV01", "Invalid hook.", `Unknown hook: "${hook}"`);
 		}
 	}
+	_addHookCallback(hook, callback) {
+		const callbacks = this._hookCallbacks.get(hook) ?? /* @__PURE__ */ new Set();
+		callbacks.add(callback);
+		this._hookCallbacks.set(hook, callbacks);
+	}
+	_emitHook(hook, response) {
+		return Promise.all([...this._hookCallbacks.get(hook) ?? []].map((callback) => Promise.resolve(callback(response))));
+	}
+	_emitHttpError = async (error) => {
+		await this._emitHook(Hooks_default.HttpRequestError, error);
+	};
+	_emitHttpFinish = () => {
+		this._emitHook(Hooks_default.HttpRequestFinish);
+	};
 	_enableRetrievingSignOutURLFromSession(config) {
 		if (config.preventSignOutURLUpdate) this._getSignOutURLFromSessionStorage = true;
 	}
@@ -2792,26 +3285,6 @@ var ThunderIDBrowserClient = class ThunderIDBrowserClient extends __thunderid_ja
 };
 var ThunderIDBrowserClient_default = ThunderIDBrowserClient;
 
-//#endregion
-//#region src/constants/Hooks.ts
-/**
-* Event hook names for attaching callbacks via `ThunderIDBrowserClient.on()`.
-*/
-let Hooks = /* @__PURE__ */ function(Hooks$1) {
-	Hooks$1["SignIn"] = "sign-in";
-	Hooks$1["SignOut"] = "sign-out";
-	Hooks$1["Initialize"] = "initialize";
-	Hooks$1["HttpRequestStart"] = "http-request-start";
-	Hooks$1["HttpRequestFinish"] = "http-request-finish";
-	Hooks$1["HttpRequestError"] = "http-request-error";
-	Hooks$1["HttpRequestSuccess"] = "http-request-success";
-	Hooks$1["RevokeAccessToken"] = "revoke-access-token";
-	Hooks$1["CustomGrant"] = "custom-grant";
-	Hooks$1["SignOutFailed"] = "sign-out-failed";
-	return Hooks$1;
-}({});
-var Hooks_default = Hooks;
-
 //#endregion
 //#region src/utils/hasAuthParamsInUrl.ts
 /**
@@ -2863,57 +3336,6 @@ const http = (client) => {
 };
 var http_default = http;
 
-//#endregion
-//#region src/utils/createHttpClientFetcher.ts
-/**
-* Builds a `fetch`-shaped function backed by the shared `FetchHttpClient` singleton, for
-* framework wrappers (`@thunderid/react`, `@thunderid/vue`) that need to hand a core
-* `@thunderid/javascript` API function a `fetcher` carrying the access token automatically.
-*
-* Unlike a plain `fetch` call, `FetchHttpClient.request` throws on a non-2xx response instead
-* of resolving it. This adapter catches that and reconstructs a `Response`-shaped object from
-* the thrown error's `response`, so the core API function sees the real status and body instead
-* of treating every non-2xx result as a network failure. A genuine network error (no response
-* attached) still propagates.
-*
-* @param instanceId - Which `FetchHttpClient` instance to use, for multi-instance apps. Defaults to `0`.
-* @returns A function matching the `(url, config) => Promise<Response>` shape core API functions expect.
-* @example
-* ```typescript
-* await updateMeCredentials({
-*   ...config,
-*   fetcher: fetcher ?? createHttpClientFetcher(instanceId),
-* });
-* ```
-*/
-const createHttpClientFetcher = (instanceId = 0) => {
-	return async (url, config) => {
-		const httpClient = FetchHttpClient_default.getInstance(instanceId);
-		const toResponse = (data, status, statusText) => ({
-			json: () => Promise.resolve(data),
-			ok: status >= 200 && status < 300,
-			status,
-			statusText,
-			text: () => Promise.resolve(typeof data === "string" ? data : JSON.stringify(data))
-		});
-		try {
-			const response = await httpClient.request({
-				data: config.body ? JSON.parse(config.body) : void 0,
-				headers: config.headers,
-				method: config.method || "POST",
-				signal: config.signal,
-				url
-			});
-			return toResponse(response.data, response.status, response.statusText || "");
-		} catch (error) {
-			const httpError = error;
-			if (httpError?.response) return toResponse(httpError.response.data, httpError.response.status, httpError.response.statusText ?? "");
-			throw error;
-		}
-	};
-};
-var createHttpClientFetcher_default = createHttpClientFetcher;
-
 //#endregion
 //#region src/utils/copyTextToClipboard.ts
 /**
@@ -3507,6 +3929,23 @@ const AVATAR_PALETTES = [
 * without needing the actual palette values.
 */
 const AVATAR_GRADIENT_COUNT = AVATAR_PALETTES.length;
+const XML_ESCAPES = {
+	"\"": "&quot;",
+	"&": "&amp;",
+	"'": "&apos;",
+	"<": "&lt;",
+	">": "&gt;"
+};
+/**
+* Escapes a caller-supplied value for interpolation into SVG text.
+*/
+const escapeXml = (value) => value.replace(/["&'<>]/g, (ch) => XML_ESCAPES[ch]);
+/**
+* Encodes an SVG document as a data URI. Lone UTF-16 surrogates are replaced with U+FFFD
+* first, since `encodeURIComponent` throws a `URIError` on them. `Array.from` iterates by
+* code point, so a surrogate it yields on its own is unpaired.
+*/
+const toSvgDataUri = (svg) => `data:image/svg+xml,${encodeURIComponent(Array.from(svg, (ch) => ch.length === 1 && ch >= "\ud800" && ch <= "\udfff" ? "�" : ch).join(""))}`;
 /**
 * Fills in `params.content` when the spec itself didn't carry one, deriving it from a raw
 * seed name (e.g. an app or user display name) — extracting initials for letter variants,
@@ -3557,11 +3996,10 @@ const generateGradientAvatar = ({ shape, variant, content, colors, bg }) => {
 	let text = "";
 	if (variant !== "blank") {
 		const letterCount = variant === "one_letter" ? 1 : 2;
-		const initials = (content || "A").toUpperCase().slice(0, letterCount);
+		const initials = escapeXml(Array.from((content || "A").toUpperCase()).slice(0, letterCount).join(""));
 		text = `<text x="50" y="64" font-family="Helvetica,Arial,sans-serif" font-weight="700" font-size="${letterCount === 1 ? 46 : 34}" text-anchor="middle" fill="#fff">${initials}</text>`;
 	}
-	const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">${defs}${shapeMarkup(shape, background)}${text}</svg>`;
-	return `data:image/svg+xml,${encodeURIComponent(svg)}`;
+	return toSvgDataUri(`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">${defs}${shapeMarkup(shape, background)}${text}</svg>`);
 };
 /**
 * Renders one of the curated anonymous-animal icons, applying the requested background
@@ -3573,8 +4011,7 @@ const generateAnonymousAnimalAvatar = ({ shape, content, bg }) => {
 	const icon = ANONYMOUS_ANIMAL_ICONS[Object.prototype.hasOwnProperty.call(ANONYMOUS_ANIMAL_ICONS, content) ? content : pickAnonymousAvatarName_default()];
 	const color = bg ?? icon.color;
 	const markup = icon.markup.replaceAll("%COLOR%", color);
-	const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">${shapeMarkup(shape, color)}${markup}</svg>`;
-	return `data:image/svg+xml,${encodeURIComponent(svg)}`;
+	return toSvgDataUri(`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">${shapeMarkup(shape, color)}${markup}</svg>`);
 };
 /**
 * Renders one of the curated anonymous-entity icons (application/organization/resource-server
@@ -3586,8 +4023,7 @@ const generateAnonymousEntityAvatar = ({ shape, content, bg }) => {
 	const icon = ANONYMOUS_ENTITY_ICONS[Object.prototype.hasOwnProperty.call(ANONYMOUS_ENTITY_ICONS, content) ? content : pickAnonymousEntityName_default()];
 	const color = bg ?? icon.color;
 	const markup = icon.markup.replaceAll("%COLOR%", color);
-	const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">${shapeMarkup(shape, color)}${markup}</svg>`;
-	return `data:image/svg+xml,${encodeURIComponent(svg)}`;
+	return toSvgDataUri(`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">${shapeMarkup(shape, color)}${markup}</svg>`);
 };
 /**
 * Generates an avatar image as an `svg+xml` data URI from a fully-resolved {@link AvatarParams}.
@@ -3704,7 +4140,8 @@ const createClassObserver = (targetElement, callback, config = {}) => {
 	return observer;
 };
 /**
-* Creates a media query listener for system theme changes
+* Creates a media query listener for system theme changes. Call `disconnect()` on the returned
+* object to remove the listener.
 */
 const createMediaQueryListener = (callback) => {
 	if (typeof window === "undefined" || !window.matchMedia) return null;
@@ -3714,7 +4151,10 @@ const createMediaQueryListener = (callback) => {
 	};
 	if (mediaQuery.addEventListener) mediaQuery.addEventListener("change", handleChange);
 	else mediaQuery.addListener(handleChange);
-	return mediaQuery;
+	return Object.assign(mediaQuery, { disconnect: () => {
+		if (mediaQuery.removeEventListener) mediaQuery.removeEventListener("change", handleChange);
+		else mediaQuery.removeListener(handleChange);
+	} });
 };
 
 //#endregion
@@ -3775,6 +4215,9 @@ exports.ANONYMOUS_ENTITY_ICONS = ANONYMOUS_ENTITY_ICONS;
 exports.AVATAR_GRADIENT_COUNT = AVATAR_GRADIENT_COUNT;
 exports.AVATAR_URI_SCHEME = AVATAR_URI_SCHEME;
 exports.AuthenticationHelper = AuthenticationHelper_default;
+exports.BACKEND_REQUEST_HEADER = BACKEND_REQUEST_HEADER;
+exports.BackendClient = BackendClient_default;
+exports.BackendHttpClient = BackendHttpClient_default;
 exports.BrowserHooks = Hooks;
 exports.BrowserStorage = BrowserStorage_default;
 exports.CUSTOM_GRANT_CONFIG = CUSTOM_GRANT_CONFIG;