@soorya-u/better-auth-desktop 0.1.0 → 0.1.2

package/README.md

@@ -113,6 +113,7 @@ export const authClient = createAuthClient({
       clientID: "my-desktop-app",
       storage: await keychainStorage(),
       // loopbackPort: 51789,  // optional; omit to bind 127.0.0.1:0 (OS-assigned)
+      // onStorageError: (err) => console.error("Keychain write failed", err),
     }),
   ],
 });
@@ -142,8 +143,12 @@ auth.onAuthenticated((user) => navigate("/app"));
 await auth.requestAuth({ provider: "github" });
 ```
 
-The bridge exposes `requestAuth`, `getUser`, `signOut`, `getUserImage`, and the
-`onAuthenticated` / `onUserUpdated` / `onAuthError` subscriptions.
+The bridge exposes: `requestAuth` (open browser flow), `getAuthUrl` (return the
+URL without opening a browser — useful for copy-link flows), `getUser`,
+`getSession`, `signOut`, `getUserImage`, `watchUser` (reactive subscription to
+the current user, race-safe), `destroy` (remove all listeners on unmount /
+hot-reload), and the `onAuthenticated` / `onUserUpdated` / `onAuthError` event
+subscriptions.
 
 No `urlSchemes` / `protocol` registration is needed in `electrobun.config.ts`.
 
@@ -199,6 +204,32 @@ const authClient = createAuthClient({ plugins: [webDesktop()] });
 authClient.forwardToDesktop();
 ```
 
+### Wrapping an auth client (renderer / web)
+
+`wrapForDesktop` proxy-wraps a `better-auth` client so that `getSession`,
+`signOut`, and `signIn.social` delegate to the desktop bridge instead of hitting
+the network directly. Pass `null` as the bridge to get the original client
+back unchanged (useful during SSR / before the bridge is initialized).
+
+```ts
+import { wrapForDesktop } from "@soorya-u/better-auth-desktop/web";
+
+// wrap once, use everywhere like a normal better-auth client
+const authClient = wrapForDesktop(baseClient, bridge);
+await authClient.signIn.social({ provider: "github" }); // → opens loopback flow
+await authClient.signOut();                               // → bridge.signOut()
+```
+
+To also intercept `useSession`, pass a framework hook as the third argument:
+
+```ts
+import { useSession } from "@soorya-u/better-auth-desktop/react"; // React
+const authClient = wrapForDesktop(baseClient, bridge, useSession);
+```
+
+Or supply your own hook for Vue / Svelte — type it with `UseSessionFn` from
+`@soorya-u/better-auth-desktop/web`.
+
 ### Customizing the loopback success page
 
 By default the loopback serves a minimal "you can close this tab" page. Override
@@ -240,7 +271,8 @@ type DesktopAdapter = {
 | `@soorya-u/better-auth-desktop/electrobun` | `electrobunDesktop()` plugin + `keychainStorage()` (Bun main process) |
 | `@soorya-u/better-auth-desktop/rpc/webview` | `defineAuthWebviewRPC()` (Electrobun renderer) |
 | `@soorya-u/better-auth-desktop/electron` | `electronDesktop()` plugin + `electronStorage()` (Electron main process) |
-| `@soorya-u/better-auth-desktop/web` | `forwardToDesktop()` + `webDesktop()` plugin (optional branded page) |
+| `@soorya-u/better-auth-desktop/web` | `wrapForDesktop()`, `forwardToDesktop()`, `webDesktop()` plugin |
+| `@soorya-u/better-auth-desktop/react` | `useSession()` React hook for the desktop bridge |
 | `@soorya-u/better-auth-desktop/client` | `desktopClient()` Better Auth client plugin |
 | `@soorya-u/better-auth-desktop/core` | shared types & utilities for custom adapters |
 

package/dist/adapters/electrobun.d.mts

@@ -1,6 +1,6 @@
-import { n as AuthUser } from "../types-h9AEfSnq.mjs";
-import { n as DesktopClientPluginOptions } from "../client-De_zQzE1.mjs";
-import { n as keychainStorage, t as KeychainStorageOptions } from "../storage-DtgX_vmE.mjs";
+import { n as AuthUser } from "../types-oAdD2Qlz.mjs";
+import { n as DesktopClientPluginOptions } from "../client-DsuEHH54.mjs";
+import { n as keychainStorage, t as KeychainStorageOptions } from "../storage-DbD61OuL.mjs";
 import * as _$_better_fetch_fetch0 from "@better-fetch/fetch";
 import { BetterFetch } from "@better-fetch/fetch";
 import { BetterAuthClientOptions, ClientStore } from "@better-auth/core";

package/dist/adapters/electrobun.mjs

@@ -1,7 +1,7 @@
-import { t as PACKAGE_VERSION } from "../version-1hEssvcU.mjs";
-import { t as createDesktopCookieLayer } from "../client-DhRcoap2.mjs";
-import { n as startAuthFlow, r as fetchUserImage } from "../exchange-DCZ0j_T5.mjs";
-import { t as keychainStorage } from "../storage-BcwDmS-W.mjs";
+import { t as PACKAGE_VERSION } from "../version-C6KnA6nF.mjs";
+import { t as createDesktopCookieLayer } from "../client-CvnA-_xx.mjs";
+import { i as fetchUserImage, r as startAuthFlow, t as buildAuthUrl } from "../exchange-D93Uwk6_.mjs";
+import { t as keychainStorage } from "../storage-DR69vdzj.mjs";
 import { BrowserView, Utils } from "electrobun/bun";
 //#region src/adapters/electrobun.ts
 function createLoopbackAdapter(getSender, storage) {
@@ -109,6 +109,24 @@ const electrobunDesktop = (options) => {
 						})
 					});
 				},
+				getAuthUrl: async ({ options: cfg }) => {
+					return await buildAuthUrl({
+						adapter,
+						$fetch,
+						clientOptions,
+						options,
+						cfg,
+						onAuthenticated: (user) => adapter.notifyRenderer({
+							type: "authenticated",
+							user
+						}),
+						onError: (error) => adapter.notifyRenderer({
+							type: "error",
+							error: error instanceof Error ? error : new Error(String(error)),
+							path: "/desktop/init-oauth-proxy"
+						})
+					});
+				},
 				getUser: async () => {
 					return await sanitizeUser((await $fetch("/get-session", {
 						method: "GET",

package/dist/adapters/electron.d.mts

@@ -1,5 +1,5 @@
-import { l as Storage } from "../types-h9AEfSnq.mjs";
-import { n as DesktopClientPluginOptions } from "../client-De_zQzE1.mjs";
+import { l as Storage } from "../types-oAdD2Qlz.mjs";
+import { n as DesktopClientPluginOptions } from "../client-DsuEHH54.mjs";
 import * as _$_better_fetch_fetch0 from "@better-fetch/fetch";
 import { BetterFetch } from "@better-fetch/fetch";
 import { BetterAuthClientOptions, ClientStore } from "@better-auth/core";
@@ -7,6 +7,7 @@ import { BetterAuthClientOptions, ClientStore } from "@better-auth/core";
 //#region src/adapters/electron.d.ts
 declare const ELECTRON_AUTH_CHANNELS: {
   readonly requestAuth: "desktop:requestAuth";
+  readonly getAuthUrl: "desktop:getAuthUrl";
   readonly getUser: "desktop:getUser";
   readonly signOut: "desktop:signOut";
   readonly getUserImage: "desktop:getUserImage";

package/dist/adapters/electron.mjs

@@ -1,11 +1,12 @@
-import { t as PACKAGE_VERSION } from "../version-1hEssvcU.mjs";
-import { t as createDesktopCookieLayer } from "../client-DhRcoap2.mjs";
-import { n as startAuthFlow, r as fetchUserImage } from "../exchange-DCZ0j_T5.mjs";
+import { t as PACKAGE_VERSION } from "../version-C6KnA6nF.mjs";
+import { t as createDesktopCookieLayer } from "../client-CvnA-_xx.mjs";
+import { i as fetchUserImage, r as startAuthFlow, t as buildAuthUrl } from "../exchange-D93Uwk6_.mjs";
 import { Buffer } from "node:buffer";
 import { createServer } from "node:http";
 //#region src/adapters/electron.ts
 const ELECTRON_AUTH_CHANNELS = {
 	requestAuth: "desktop:requestAuth",
+	getAuthUrl: "desktop:getAuthUrl",
 	getUser: "desktop:getUser",
 	signOut: "desktop:signOut",
 	getUserImage: "desktop:getUserImage",
@@ -56,7 +57,7 @@ function createLoopbackAdapter(shell, getWindow, storage) {
 	return {
 		openExternal: (url) => shell.openExternal(url),
 		serveLoopback(onRequest, opts) {
-			return new Promise((resolve) => {
+			return new Promise((resolve, reject) => {
 				const server = createServer(async (req, res) => {
 					const url = new URL(req.url ?? "/", "http://127.0.0.1");
 					const query = {};
@@ -70,7 +71,16 @@ function createLoopbackAdapter(shell, getWindow, storage) {
 					res.writeHead(out.status, out.headers);
 					res.end(out.body);
 				});
+				const timer = setTimeout(() => {
+					server.close();
+					reject(/* @__PURE__ */ new Error("Loopback server timed out waiting for port"));
+				}, 1e4);
+				server.on("error", (err) => {
+					clearTimeout(timer);
+					reject(err);
+				});
 				server.listen(opts?.port ?? 0, "127.0.0.1", () => {
+					clearTimeout(timer);
 					const address = server.address();
 					resolve({
 						port: typeof address === "object" && address ? address.port : 0,
@@ -156,6 +166,24 @@ const electronDesktop = (options) => {
 							})
 						});
 					});
+					ipcMain.handle(ELECTRON_AUTH_CHANNELS.getAuthUrl, async (_event, cfg) => {
+						return await buildAuthUrl({
+							adapter,
+							$fetch,
+							clientOptions,
+							options,
+							cfg,
+							onAuthenticated: (user) => adapter.notifyRenderer({
+								type: "authenticated",
+								user
+							}),
+							onError: (error) => adapter.notifyRenderer({
+								type: "error",
+								error: error instanceof Error ? error : new Error(String(error)),
+								path: "/desktop/init-oauth-proxy"
+							})
+						});
+					});
 					ipcMain.handle(ELECTRON_AUTH_CHANNELS.getUser, async () => {
 						return await sanitizeUser((await $fetch("/get-session", {
 							method: "GET",
@@ -192,6 +220,7 @@ const electronDesktop = (options) => {
 					return () => {
 						unsub?.();
 						ipcMain.removeHandler(ELECTRON_AUTH_CHANNELS.requestAuth);
+						ipcMain.removeHandler(ELECTRON_AUTH_CHANNELS.getAuthUrl);
 						ipcMain.removeHandler(ELECTRON_AUTH_CHANNELS.getUser);
 						ipcMain.removeHandler(ELECTRON_AUTH_CHANNELS.signOut);
 						ipcMain.removeHandler(ELECTRON_AUTH_CHANNELS.getUserImage);

package/dist/{client-DhRcoap2.mjs → client-CvnA-_xx.mjs}

@@ -1,4 +1,4 @@
-import { t as PACKAGE_VERSION } from "./version-1hEssvcU.mjs";
+import { t as PACKAGE_VERSION } from "./version-C6KnA6nF.mjs";
 import { cookieNameRegex, parseSetCookieHeader } from "better-auth/cookies";
 //#region src/core/cookies.ts
 function getSetCookie(header, prevCookie) {
@@ -64,7 +64,9 @@ function createDesktopCookieLayer(options) {
 	const setStored = (name, value) => {
 		try {
 			opts.storage.setItem(name, value);
-		} catch {}
+		} catch (error) {
+			opts.onStorageError?.(error);
+		}
 	};
 	let store = null;
 	let serverOrigin;

package/dist/{client-De_zQzE1.d.mts → client-DsuEHH54.d.mts}

@@ -1,4 +1,4 @@
-import { i as DesktopClientOptions, l as Storage } from "./types-h9AEfSnq.mjs";
+import { i as DesktopClientOptions, l as Storage } from "./types-oAdD2Qlz.mjs";
 import { BetterFetch, BetterFetchPlugin } from "@better-fetch/fetch";
 import { BetterAuthClientOptions, ClientStore } from "@better-auth/core";
 

package/dist/client.d.mts

@@ -1,3 +1,3 @@
-import { i as DesktopClientOptions, l as Storage } from "./types-h9AEfSnq.mjs";
-import { a as desktopClient, n as DesktopClientPluginOptions, t as DesktopClientInternals } from "./client-De_zQzE1.mjs";
+import { i as DesktopClientOptions, l as Storage } from "./types-oAdD2Qlz.mjs";
+import { a as desktopClient, n as DesktopClientPluginOptions, t as DesktopClientInternals } from "./client-DsuEHH54.mjs";
 export { type DesktopClientInternals, type DesktopClientOptions, type DesktopClientPluginOptions, type Storage, desktopClient };

package/dist/client.mjs

@@ -1,2 +1,2 @@
-import { n as desktopClient } from "./client-DhRcoap2.mjs";
+import { n as desktopClient } from "./client-CvnA-_xx.mjs";
 export { desktopClient };

package/dist/core/index.d.mts

@@ -1,6 +1,6 @@
-import { a as LoopbackRequest, c as RequestAuthOptions, i as DesktopClientOptions, l as Storage, n as AuthUser, o as LoopbackResponse, r as DesktopAdapter, s as LoopbackServer, t as AuthEvent } from "../types-h9AEfSnq.mjs";
-import { a as desktopClient, i as createDesktopCookieLayer, n as DesktopClientPluginOptions, r as DesktopCookieLayer, t as DesktopClientInternals } from "../client-De_zQzE1.mjs";
-import { n as keychainStorage, t as KeychainStorageOptions } from "../storage-DtgX_vmE.mjs";
-import { a as StartAuthFlowArgs, i as ExchangeTokenArgs, n as fetchUserImage, o as exchangeToken, r as normalizeUserOutput, s as startAuthFlow, t as FetchUserImageResult } from "../index-CP_2Wlut.mjs";
-import { a as isAllowedLoopbackPort, i as generateNonce, n as LOOPBACK_HOST, o as parseLoopbackUrl, r as buildLoopbackUrl, s as successPage, t as AllowedLoopbackPorts } from "../loopback-ClkAoS2u.mjs";
-export { AllowedLoopbackPorts, AuthEvent, AuthUser, DesktopAdapter, DesktopClientInternals, DesktopClientOptions, DesktopClientPluginOptions, DesktopCookieLayer, ExchangeTokenArgs, FetchUserImageResult, KeychainStorageOptions, LOOPBACK_HOST, LoopbackRequest, LoopbackResponse, LoopbackServer, RequestAuthOptions, StartAuthFlowArgs, Storage, buildLoopbackUrl, createDesktopCookieLayer, desktopClient, exchangeToken, fetchUserImage, generateNonce, isAllowedLoopbackPort, keychainStorage, normalizeUserOutput, parseLoopbackUrl, startAuthFlow, successPage };
+import { a as LoopbackRequest, c as RequestAuthOptions, i as DesktopClientOptions, l as Storage, n as AuthUser, o as LoopbackResponse, r as DesktopAdapter, s as LoopbackServer, t as AuthEvent } from "../types-oAdD2Qlz.mjs";
+import { a as desktopClient, i as createDesktopCookieLayer, n as DesktopClientPluginOptions, r as DesktopCookieLayer, t as DesktopClientInternals } from "../client-DsuEHH54.mjs";
+import { n as keychainStorage, t as KeychainStorageOptions } from "../storage-DbD61OuL.mjs";
+import { a as StartAuthFlowArgs, i as ExchangeTokenArgs, n as fetchUserImage, o as exchangeToken, r as normalizeUserOutput, s as startAuthFlow, t as FetchUserImageResult } from "../index-xd3h5rM3.mjs";
+import { a as isAllowedLoopbackPort, i as generateNonce, n as LOOPBACK_HOST, o as parseLoopbackUrl, r as buildLoopbackUrl, t as AllowedLoopbackPorts } from "../loopback-Dec4O7Rx.mjs";
+export { AllowedLoopbackPorts, AuthEvent, AuthUser, DesktopAdapter, DesktopClientInternals, DesktopClientOptions, DesktopClientPluginOptions, DesktopCookieLayer, ExchangeTokenArgs, FetchUserImageResult, KeychainStorageOptions, LOOPBACK_HOST, LoopbackRequest, LoopbackResponse, LoopbackServer, RequestAuthOptions, StartAuthFlowArgs, Storage, buildLoopbackUrl, createDesktopCookieLayer, desktopClient, exchangeToken, fetchUserImage, generateNonce, isAllowedLoopbackPort, keychainStorage, normalizeUserOutput, parseLoopbackUrl, startAuthFlow };

package/dist/core/index.mjs

@@ -1,5 +1,5 @@
-import { n as desktopClient, t as createDesktopCookieLayer } from "../client-DhRcoap2.mjs";
-import { a as parseLoopbackUrl, i as isAllowedLoopbackPort, n as buildLoopbackUrl, o as successPage, r as generateNonce, t as LOOPBACK_HOST } from "../loopback-DTQgg1Za.mjs";
-import { i as normalizeUserOutput, n as startAuthFlow, r as fetchUserImage, t as exchangeToken } from "../exchange-DCZ0j_T5.mjs";
-import { t as keychainStorage } from "../storage-BcwDmS-W.mjs";
-export { LOOPBACK_HOST, buildLoopbackUrl, createDesktopCookieLayer, desktopClient, exchangeToken, fetchUserImage, generateNonce, isAllowedLoopbackPort, keychainStorage, normalizeUserOutput, parseLoopbackUrl, startAuthFlow, successPage };
+import { n as desktopClient, t as createDesktopCookieLayer } from "../client-CvnA-_xx.mjs";
+import { a as parseLoopbackUrl, i as isAllowedLoopbackPort, n as buildLoopbackUrl, r as generateNonce, t as LOOPBACK_HOST } from "../loopback-CNOfW74-.mjs";
+import { a as normalizeUserOutput, i as fetchUserImage, n as exchangeToken, r as startAuthFlow } from "../exchange-D93Uwk6_.mjs";
+import { t as keychainStorage } from "../storage-DR69vdzj.mjs";
+export { LOOPBACK_HOST, buildLoopbackUrl, createDesktopCookieLayer, desktopClient, exchangeToken, fetchUserImage, generateNonce, isAllowedLoopbackPort, keychainStorage, normalizeUserOutput, parseLoopbackUrl, startAuthFlow };

package/dist/{exchange-DCZ0j_T5.mjs → exchange-D93Uwk6_.mjs}

@@ -1,4 +1,4 @@
-import { n as buildLoopbackUrl, o as successPage, r as generateNonce } from "./loopback-DTQgg1Za.mjs";
+import { n as buildLoopbackUrl, r as generateNonce } from "./loopback-CNOfW74-.mjs";
 import { BetterAuthError } from "@better-auth/core/error";
 import { base64, base64Url } from "@better-auth/utils/base64";
 import { createHash } from "@better-auth/utils/hash";
@@ -28,22 +28,31 @@ async function fetchUserImage(baseURL, url) {
 	} catch {
 		return null;
 	}
-	const response = await fetch(resolvedUrl, {
-		method: "GET",
-		headers: { accept: "image/*" }
-	});
-	if (!response.ok) return null;
-	const contentType = response.headers.get("content-type");
-	if (!contentType?.startsWith("image/") || contentType.startsWith("image/svg")) return null;
-	const contentLength = response.headers.get("content-length");
-	if (contentLength && Number(contentLength) > DEFAULT_MAX_BYTES) return null;
-	const buf = await response.arrayBuffer();
-	const bytes = new Uint8Array(buf);
-	if (bytes.byteLength > DEFAULT_MAX_BYTES) return null;
-	return {
-		bytes,
-		mimeType: contentType.split(";")[0]?.trim() || "image/png"
-	};
+	const controller = new AbortController();
+	const fetchTimer = setTimeout(() => controller.abort(), 1e4);
+	try {
+		const response = await fetch(resolvedUrl, {
+			method: "GET",
+			headers: { accept: "image/*" },
+			signal: controller.signal
+		});
+		if (!response.ok) return null;
+		const contentType = response.headers.get("content-type");
+		if (!contentType?.startsWith("image/") || contentType.startsWith("image/svg")) return null;
+		const contentLength = response.headers.get("content-length");
+		if (contentLength && Number(contentLength) > DEFAULT_MAX_BYTES) return null;
+		const buf = await response.arrayBuffer();
+		const bytes = new Uint8Array(buf);
+		if (bytes.byteLength > DEFAULT_MAX_BYTES) return null;
+		return {
+			bytes,
+			mimeType: contentType.split(";")[0]?.trim() || "image/png"
+		};
+	} catch {
+		return null;
+	} finally {
+		clearTimeout(fetchTimer);
+	}
 }
 function normalizeUserOutput(user, _options) {
 	return { ...user };
@@ -100,10 +109,15 @@ function loopbackSuccessResponse(success) {
 		headers: { location: success.redirectTo },
 		body: ""
 	};
-	return {
+	if (typeof success === "string") return {
 		status: 200,
 		headers: { "content-type": "text/html; charset=utf-8" },
-		body: success ?? successPage()
+		body: success
+	};
+	return {
+		status: 200,
+		headers: { "content-type": "text/plain; charset=utf-8" },
+		body: "Authentication complete. You can close this tab."
 	};
 }
 async function sanitize(user, options) {
@@ -117,6 +131,10 @@ async function sanitize(user, options) {
 	if (u !== null) u = normalizeUserOutput(u, options);
 	return u;
 }
+/**
+* Decodes the redirect token, looks up the matching PKCE verifier, and
+* exchanges it at `/desktop/token`. Called automatically by the loopback handler.
+*/
 async function exchangeToken({ $fetch, options, token, onAuthenticated, fetchOptions }) {
 	const decoded = safeJSONParse(new TextDecoder().decode(base64Url.decode(decodeURIComponent(token))));
 	const codeVerifier = decoded ? verifierStore.get(decoded.state) : void 0;
@@ -139,7 +157,7 @@ async function exchangeToken({ $fetch, options, token, onAuthenticated, fetchOpt
 		}
 	});
 }
-async function startAuthFlow({ adapter, $fetch, clientOptions, options, cfg, onAuthenticated, onError }) {
+async function prepareAuthFlow({ adapter, $fetch, clientOptions, options, cfg, onAuthenticated, onError }) {
 	const baseURL = getBaseURL(clientOptions?.baseURL, clientOptions?.basePath, void 0, true);
 	if (!baseURL) throw new BetterAuthError("Base URL is required to start a desktop sign-in flow.");
 	const state = generateRandomString(16, "A-Z", "a-z", "0-9");
@@ -157,40 +175,45 @@ async function startAuthFlow({ adapter, $fetch, clientOptions, options, cfg, onA
 		server = null;
 		verifierStore.delete(state);
 	};
-	server = await adapter.serveLoopback(async (req) => {
-		if (req.path !== loopbackPath) return {
-			status: 404,
-			body: "Not found"
-		};
-		if (req.query.nonce !== nonce) return {
-			status: 403,
-			body: "Forbidden"
-		};
-		const token = req.query.token;
-		if (!token) return {
-			status: 400,
-			body: "Missing token"
-		};
-		try {
-			await exchangeToken({
-				$fetch,
-				options,
-				token,
-				onAuthenticated,
-				fetchOptions: { throw: true }
-			});
-		} catch (error) {
-			cleanup();
-			onError?.(error);
-			return {
-				status: 500,
-				headers: { "content-type": "text/plain; charset=utf-8" },
-				body: "Sign-in failed. You can close this tab."
+	try {
+		server = await adapter.serveLoopback(async (req) => {
+			if (req.path !== loopbackPath) return {
+				status: 404,
+				body: "Not found"
 			};
-		}
-		cleanup();
-		return loopbackSuccessResponse(options.loopbackSuccess);
-	}, { port: options.loopbackPort });
+			if (req.query.nonce !== nonce) return {
+				status: 403,
+				body: "Forbidden"
+			};
+			const token = req.query.token;
+			if (!token) return {
+				status: 400,
+				body: "Missing token"
+			};
+			try {
+				await exchangeToken({
+					$fetch,
+					options,
+					token,
+					onAuthenticated,
+					fetchOptions: { throw: true }
+				});
+			} catch (error) {
+				cleanup();
+				onError?.(error);
+				return {
+					status: 500,
+					headers: { "content-type": "text/plain; charset=utf-8" },
+					body: "Sign-in failed. You can close this tab."
+				};
+			}
+			cleanup();
+			return loopbackSuccessResponse(options.loopbackSuccess);
+		}, { port: options.loopbackPort });
+	} catch (error) {
+		verifierStore.delete(state);
+		throw error;
+	}
 	const loopbackUrl = buildLoopbackUrl(server.port, loopbackPath, nonce);
 	const url = new URL(`${baseURL}/desktop/init-oauth-proxy`);
 	for (const [key, value] of Object.entries(cfg)) {
@@ -206,12 +229,28 @@ async function startAuthFlow({ adapter, $fetch, clientOptions, options, cfg, onA
 		cleanup();
 		onError?.(new BetterAuthError("Desktop sign-in timed out."));
 	}, options.loopbackTimeout ?? DEFAULT_LOOPBACK_TIMEOUT);
+	return {
+		url: url.toString(),
+		cleanup
+	};
+}
+/**
+* Returns the init-oauth-proxy URL without opening a browser.
+* The loopback server starts listening in the background — use for copy-link flows.
+*/
+async function buildAuthUrl(args) {
+	const { url } = await prepareAuthFlow(args);
+	return url;
+}
+/** Opens the init-oauth-proxy URL in the system browser and awaits the loopback callback. */
+async function startAuthFlow(args) {
+	const { url, cleanup } = await prepareAuthFlow(args);
 	try {
-		await adapter.openExternal(url.toString());
+		await args.adapter.openExternal(url);
 	} catch (error) {
 		cleanup();
 		throw error;
 	}
 }
 //#endregion
-export { normalizeUserOutput as i, startAuthFlow as n, fetchUserImage as r, exchangeToken as t };
+export { normalizeUserOutput as a, fetchUserImage as i, exchangeToken as n, startAuthFlow as r, buildAuthUrl as t };

package/dist/{index-CP_2Wlut.d.mts → index-xd3h5rM3.d.mts}

@@ -1,4 +1,4 @@
-import { c as RequestAuthOptions, i as DesktopClientOptions, n as AuthUser, r as DesktopAdapter } from "./types-h9AEfSnq.mjs";
+import { c as RequestAuthOptions, i as DesktopClientOptions, n as AuthUser, r as DesktopAdapter } from "./types-oAdD2Qlz.mjs";
 import { BetterFetch, CreateFetchOption } from "@better-fetch/fetch";
 import { BetterAuthClientOptions } from "@better-auth/core";
 import { User } from "@better-auth/core/db";
@@ -11,6 +11,10 @@ type ExchangeTokenArgs = {
   onAuthenticated: (user: AuthUser) => void;
   fetchOptions?: Omit<CreateFetchOption, "method"> | undefined;
 };
+/**
+ * Decodes the redirect token, looks up the matching PKCE verifier, and
+ * exchanges it at `/desktop/token`. Called automatically by the loopback handler.
+ */
 declare function exchangeToken({
   $fetch,
   options,
@@ -40,15 +44,8 @@ type StartAuthFlowArgs = {
   onAuthenticated: (user: AuthUser) => void;
   onError?: (error: unknown) => void;
 };
-declare function startAuthFlow({
-  adapter,
-  $fetch,
-  clientOptions,
-  options,
-  cfg,
-  onAuthenticated,
-  onError
-}: StartAuthFlowArgs): Promise<void>;
+/** Opens the init-oauth-proxy URL in the system browser and awaits the loopback callback. */
+declare function startAuthFlow(args: StartAuthFlowArgs): Promise<void>;
 //#endregion
 //#region src/core/user.d.ts
 type FetchUserImageResult = {

package/dist/index.d.mts

@@ -1,10 +1,10 @@
-import { a as LoopbackRequest, c as RequestAuthOptions, i as DesktopClientOptions, l as Storage, n as AuthUser, o as LoopbackResponse, r as DesktopAdapter, s as LoopbackServer, t as AuthEvent } from "./types-h9AEfSnq.mjs";
-import { a as desktopClient, i as createDesktopCookieLayer, n as DesktopClientPluginOptions, r as DesktopCookieLayer, t as DesktopClientInternals } from "./client-De_zQzE1.mjs";
-import { n as keychainStorage, t as KeychainStorageOptions } from "./storage-DtgX_vmE.mjs";
-import { a as StartAuthFlowArgs, i as ExchangeTokenArgs, n as fetchUserImage, o as exchangeToken, r as normalizeUserOutput, s as startAuthFlow, t as FetchUserImageResult } from "./index-CP_2Wlut.mjs";
-import { a as isAllowedLoopbackPort, i as generateNonce, n as LOOPBACK_HOST, o as parseLoopbackUrl, r as buildLoopbackUrl, s as successPage, t as AllowedLoopbackPorts } from "./loopback-ClkAoS2u.mjs";
+import { a as LoopbackRequest, c as RequestAuthOptions, i as DesktopClientOptions, l as Storage, n as AuthUser, o as LoopbackResponse, r as DesktopAdapter, s as LoopbackServer, t as AuthEvent } from "./types-oAdD2Qlz.mjs";
+import { a as desktopClient, i as createDesktopCookieLayer, n as DesktopClientPluginOptions, r as DesktopCookieLayer, t as DesktopClientInternals } from "./client-DsuEHH54.mjs";
+import { n as keychainStorage, t as KeychainStorageOptions } from "./storage-DbD61OuL.mjs";
+import { a as StartAuthFlowArgs, i as ExchangeTokenArgs, n as fetchUserImage, o as exchangeToken, r as normalizeUserOutput, s as startAuthFlow, t as FetchUserImageResult } from "./index-xd3h5rM3.mjs";
+import { a as isAllowedLoopbackPort, i as generateNonce, n as LOOPBACK_HOST, o as parseLoopbackUrl, r as buildLoopbackUrl, t as AllowedLoopbackPorts } from "./loopback-Dec4O7Rx.mjs";
 
 //#region src/version.d.ts
 declare const PACKAGE_VERSION: string;
 //#endregion
-export { AllowedLoopbackPorts, AuthEvent, AuthUser, DesktopAdapter, DesktopClientInternals, DesktopClientOptions, DesktopClientPluginOptions, DesktopCookieLayer, ExchangeTokenArgs, FetchUserImageResult, KeychainStorageOptions, LOOPBACK_HOST, LoopbackRequest, LoopbackResponse, LoopbackServer, PACKAGE_VERSION, RequestAuthOptions, StartAuthFlowArgs, Storage, buildLoopbackUrl, createDesktopCookieLayer, desktopClient, exchangeToken, fetchUserImage, generateNonce, isAllowedLoopbackPort, keychainStorage, normalizeUserOutput, parseLoopbackUrl, startAuthFlow, successPage };
+export { AllowedLoopbackPorts, AuthEvent, AuthUser, DesktopAdapter, DesktopClientInternals, DesktopClientOptions, DesktopClientPluginOptions, DesktopCookieLayer, ExchangeTokenArgs, FetchUserImageResult, KeychainStorageOptions, LOOPBACK_HOST, LoopbackRequest, LoopbackResponse, LoopbackServer, PACKAGE_VERSION, RequestAuthOptions, StartAuthFlowArgs, Storage, buildLoopbackUrl, createDesktopCookieLayer, desktopClient, exchangeToken, fetchUserImage, generateNonce, isAllowedLoopbackPort, keychainStorage, normalizeUserOutput, parseLoopbackUrl, startAuthFlow };

package/dist/index.mjs

@@ -1,7 +1,7 @@
-import { t as PACKAGE_VERSION } from "./version-1hEssvcU.mjs";
-import { n as desktopClient, t as createDesktopCookieLayer } from "./client-DhRcoap2.mjs";
-import { a as parseLoopbackUrl, i as isAllowedLoopbackPort, n as buildLoopbackUrl, o as successPage, r as generateNonce, t as LOOPBACK_HOST } from "./loopback-DTQgg1Za.mjs";
-import { i as normalizeUserOutput, n as startAuthFlow, r as fetchUserImage, t as exchangeToken } from "./exchange-DCZ0j_T5.mjs";
-import { t as keychainStorage } from "./storage-BcwDmS-W.mjs";
+import { t as PACKAGE_VERSION } from "./version-C6KnA6nF.mjs";
+import { n as desktopClient, t as createDesktopCookieLayer } from "./client-CvnA-_xx.mjs";
+import { a as parseLoopbackUrl, i as isAllowedLoopbackPort, n as buildLoopbackUrl, r as generateNonce, t as LOOPBACK_HOST } from "./loopback-CNOfW74-.mjs";
+import { a as normalizeUserOutput, i as fetchUserImage, n as exchangeToken, r as startAuthFlow } from "./exchange-D93Uwk6_.mjs";
+import { t as keychainStorage } from "./storage-DR69vdzj.mjs";
 import "./core/index.mjs";
-export { LOOPBACK_HOST, PACKAGE_VERSION, buildLoopbackUrl, createDesktopCookieLayer, desktopClient, exchangeToken, fetchUserImage, generateNonce, isAllowedLoopbackPort, keychainStorage, normalizeUserOutput, parseLoopbackUrl, startAuthFlow, successPage };
+export { LOOPBACK_HOST, PACKAGE_VERSION, buildLoopbackUrl, createDesktopCookieLayer, desktopClient, exchangeToken, fetchUserImage, generateNonce, isAllowedLoopbackPort, keychainStorage, normalizeUserOutput, parseLoopbackUrl, startAuthFlow };

package/dist/{loopback-DTQgg1Za.mjs → loopback-CNOfW74-.mjs}

@@ -10,6 +10,10 @@ function buildLoopbackUrl(port, path, nonce) {
 	url.searchParams.set("nonce", nonce);
 	return url.toString();
 }
+/**
+* Returns `null` for anything other than a plain-http `127.0.0.1` URL so
+* callers can safely reject untrusted redirect targets (never `localhost`, never https).
+*/
 function parseLoopbackUrl(raw, allowedPorts) {
 	let url;
 	try {
@@ -28,8 +32,5 @@ function isAllowedLoopbackPort(port, allowed) {
 	if (Array.isArray(allowed)) return allowed.includes(port);
 	return port >= allowed.min && port <= allowed.max;
 }
-function successPage(title = "Signed in", message = "You can close this tab and return to the app.") {
-	return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${title}</title></head><body style="font-family:system-ui,sans-serif;display:grid;place-items:center;min-height:100vh;margin:0;text-align:center"><main><h1 style="font-size:1.25rem;margin:0 0 .5rem">${title}</h1><p style="margin:0;opacity:.7">${message}</p></main></body></html>`;
-}
 //#endregion
-export { parseLoopbackUrl as a, isAllowedLoopbackPort as i, buildLoopbackUrl as n, successPage as o, generateNonce as r, LOOPBACK_HOST as t };
+export { parseLoopbackUrl as a, isAllowedLoopbackPort as i, buildLoopbackUrl as n, generateNonce as r, LOOPBACK_HOST as t };

package/dist/{loopback-ClkAoS2u.d.mts → loopback-Dec4O7Rx.d.mts}

@@ -6,8 +6,11 @@ type AllowedLoopbackPorts = number[] | {
 };
 declare function generateNonce(): string;
 declare function buildLoopbackUrl(port: number, path: string, nonce: string): string;
+/**
+ * Returns `null` for anything other than a plain-http `127.0.0.1` URL so
+ * callers can safely reject untrusted redirect targets (never `localhost`, never https).
+ */
 declare function parseLoopbackUrl(raw: string, allowedPorts?: AllowedLoopbackPorts): URL | null;
 declare function isAllowedLoopbackPort(port: number, allowed: AllowedLoopbackPorts): boolean;
-declare function successPage(title?: string, message?: string): string;
 //#endregion
-export { isAllowedLoopbackPort as a, generateNonce as i, LOOPBACK_HOST as n, parseLoopbackUrl as o, buildLoopbackUrl as r, successPage as s, AllowedLoopbackPorts as t };
+export { isAllowedLoopbackPort as a, generateNonce as i, LOOPBACK_HOST as n, parseLoopbackUrl as o, buildLoopbackUrl as r, AllowedLoopbackPorts as t };

package/dist/react.d.mts

@@ -0,0 +1,14 @@
+import { n as AuthUser } from "./types-oAdD2Qlz.mjs";
+import { t as AuthBridges } from "./schema-CE7bJ4bb.mjs";
+
+//#region src/react.d.ts
+/** React hook that subscribes to the desktop bridge user session. Must be called from a component or another hook. */
+declare function useSession<TUser extends AuthUser = AuthUser>(bridge: AuthBridges<TUser> | null): {
+  data: {
+    user: TUser;
+  } | null;
+  isPending: boolean;
+  error: unknown;
+};
+//#endregion
+export { useSession };

package/dist/react.mjs

@@ -0,0 +1,31 @@
+import { useEffect, useState } from "react";
+//#region src/react.ts
+/** React hook that subscribes to the desktop bridge user session. Must be called from a component or another hook. */
+function useSession(bridge) {
+	const [data, setData] = useState(null);
+	const [isPending, setIsPending] = useState(true);
+	useEffect(() => {
+		setData(null);
+		setIsPending(true);
+		if (!bridge) {
+			setIsPending(false);
+			return;
+		}
+		let settled = false;
+		const settle = (user) => {
+			if (!settled) {
+				settled = true;
+				setIsPending(false);
+			}
+			setData(user ? { user } : null);
+		};
+		return bridge.watchUser(settle);
+	}, [bridge]);
+	return {
+		data,
+		isPending,
+		error: null
+	};
+}
+//#endregion
+export { useSession };

package/dist/rpc/webview.d.mts

@@ -1,26 +1,8 @@
-import { c as RequestAuthOptions } from "../types-h9AEfSnq.mjs";
-import { BetterFetchError } from "@better-fetch/fetch";
-import { User } from "@better-auth/core/db";
+import { n as AuthUser } from "../types-oAdD2Qlz.mjs";
+import { t as AuthBridges } from "../schema-CE7bJ4bb.mjs";
 
-//#region src/rpc/schema.d.ts
-type AuthBridges = {
-  getUser(): Promise<(User & Record<string, any>) | null>;
-  requestAuth(options: RequestAuthOptions): Promise<void>;
-  signOut(): Promise<void>;
-  getUserImage(url: string): Promise<{
-    dataUrl: string | null;
-  }>;
-  onAuthenticated(callback: (user: User & Record<string, any>) => void): () => void;
-  onUserUpdated(callback: (user: (User & Record<string, any>) | null) => void): () => void;
-  onAuthError(callback: (context: {
-    error: BetterFetchError | {
-      message: string;
-    };
-    path?: string;
-  }) => void): () => void;
-};
-//#endregion
 //#region src/rpc/webview.d.ts
-declare function defineAuthWebviewRPC(): AuthBridges;
+/** Initializes the Electrobun webview RPC and returns the desktop bridge. */
+declare function defineAuthWebviewRPC<TUser extends AuthUser = AuthUser>(): AuthBridges<TUser>;
 //#endregion
 export { defineAuthWebviewRPC };

package/dist/rpc/webview.mjs

@@ -278,18 +278,7 @@ var Electroview = class {
 };
 //#endregion
 //#region src/rpc/webview.ts
-/**
-* Renderer-side auth bridge for the Electrobun WebView. Call once at the top of
-* your webview entry, then use the returned bridge:
-*
-* ```ts
-* import { defineAuthWebviewRPC } from "@soorya-u/better-auth-desktop/rpc/webview";
-* export const auth = defineAuthWebviewRPC();
-*
-* auth.onAuthenticated((user) => navigate("/threads"));
-* await auth.requestAuth({ provider: "github" });
-* ```
-*/
+/** Initializes the Electrobun webview RPC and returns the desktop bridge. */
 function defineAuthWebviewRPC() {
 	const rpc = Electroview.defineRPC({
 		maxRequestTime: 3e4,
@@ -299,25 +288,70 @@ function defineAuthWebviewRPC() {
 		}
 	});
 	new Electroview({ rpc });
+	const teardowns = /* @__PURE__ */ new Set();
+	const track = (off) => {
+		teardowns.add(off);
+		return () => {
+			off();
+			teardowns.delete(off);
+		};
+	};
 	return {
 		getUser: () => rpc.request.getUser({}),
+		getSession: () => rpc.request.getUser({}).then((user) => ({
+			data: user ? { user } : null,
+			error: null
+		})).catch((error) => ({
+			data: null,
+			error
+		})),
+		watchUser: (callback) => {
+			let disposed = false;
+			let sawEvent = false;
+			const apply = (user) => {
+				sawEvent = true;
+				if (!disposed) callback(user);
+			};
+			const authHandler = (user) => apply(user);
+			const updateHandler = (user) => apply(user);
+			rpc.addMessageListener("onAuthenticated", authHandler);
+			rpc.addMessageListener("onUserUpdated", updateHandler);
+			rpc.request.getUser({}).then((user) => {
+				if (!disposed && !sawEvent) callback(user);
+			}).catch(() => {
+				if (!disposed && !sawEvent) callback(null);
+			});
+			const cleanup = () => {
+				disposed = true;
+				rpc.removeMessageListener("onAuthenticated", authHandler);
+				rpc.removeMessageListener("onUserUpdated", updateHandler);
+				teardowns.delete(cleanup);
+			};
+			teardowns.add(cleanup);
+			return cleanup;
+		},
 		requestAuth: (options) => rpc.request.requestAuth({ options }),
+		getAuthUrl: (options) => rpc.request.getAuthUrl({ options }),
 		signOut: () => rpc.request.signOut({}),
 		getUserImage: (url) => rpc.request.getUserImage({ url }),
 		onAuthenticated: (callback) => {
 			const handler = (user) => callback(user);
 			rpc.addMessageListener("onAuthenticated", handler);
-			return () => rpc.removeMessageListener("onAuthenticated", handler);
+			return track(() => rpc.removeMessageListener("onAuthenticated", handler));
 		},
 		onUserUpdated: (callback) => {
 			const handler = (user) => callback(user);
 			rpc.addMessageListener("onUserUpdated", handler);
-			return () => rpc.removeMessageListener("onUserUpdated", handler);
+			return track(() => rpc.removeMessageListener("onUserUpdated", handler));
 		},
 		onAuthError: (callback) => {
 			const handler = (ctx) => callback(ctx);
 			rpc.addMessageListener("onAuthError", handler);
-			return () => rpc.removeMessageListener("onAuthError", handler);
+			return track(() => rpc.removeMessageListener("onAuthError", handler));
+		},
+		destroy: () => {
+			for (const off of teardowns) off();
+			teardowns.clear();
 		}
 	};
 }

package/dist/schema-CE7bJ4bb.d.mts

@@ -0,0 +1,33 @@
+import { c as RequestAuthOptions, n as AuthUser } from "./types-oAdD2Qlz.mjs";
+import { BetterFetchError } from "@better-fetch/fetch";
+import { User } from "@better-auth/core/db";
+
+//#region src/rpc/schema.d.ts
+type SessionResult<TUser> = {
+  data: {
+    user: TUser;
+  } | null;
+  error: unknown;
+};
+type AuthBridges<TUser extends AuthUser = AuthUser> = {
+  getUser(): Promise<TUser | null>;
+  getSession(): Promise<SessionResult<TUser>>;
+  watchUser(callback: (user: TUser | null) => void): () => void;
+  requestAuth(options: RequestAuthOptions): Promise<void>;
+  getAuthUrl(options: RequestAuthOptions): Promise<string>;
+  signOut(): Promise<void>;
+  getUserImage(url: string): Promise<{
+    dataUrl: string | null;
+  }>;
+  onAuthenticated(callback: (user: TUser) => void): () => void;
+  onUserUpdated(callback: (user: TUser | null) => void): () => void;
+  onAuthError(callback: (context: {
+    error: BetterFetchError | {
+      message: string;
+    };
+    path?: string;
+  }) => void): () => void;
+  destroy(): void;
+};
+//#endregion
+export { AuthBridges as t };

package/dist/server/index.d.mts

@@ -1,4 +1,4 @@
-import { t as AllowedLoopbackPorts } from "../loopback-ClkAoS2u.mjs";
+import { t as AllowedLoopbackPorts } from "../loopback-Dec4O7Rx.mjs";
 import * as _$better_auth0 from "better-auth";
 import { BetterAuthPlugin } from "better-auth";
 

package/dist/server/index.mjs

@@ -1,5 +1,5 @@
-import { t as PACKAGE_VERSION } from "../version-1hEssvcU.mjs";
-import { a as parseLoopbackUrl } from "../loopback-DTQgg1Za.mjs";
+import { t as PACKAGE_VERSION } from "../version-C6KnA6nF.mjs";
+import { a as parseLoopbackUrl } from "../loopback-CNOfW74-.mjs";
 import { setSessionCookie } from "better-auth/cookies";
 import { APIError, BASE_ERROR_CODES } from "@better-auth/core/error";
 import { base64Url } from "@better-auth/utils/base64";

package/dist/{storage-BcwDmS-W.mjs → storage-DR69vdzj.mjs}

@@ -16,7 +16,7 @@ async function keychainStorage(opts = {}) {
 			service,
 			name: account,
 			value: JSON.stringify(cache)
-		}).catch(() => void 0);
+		}).catch((error) => opts.onError?.(error));
 	};
 	return {
 		getItem: (name) => cache[name] ?? null,

package/dist/storage-DbD61OuL.d.mts

@@ -0,0 +1,11 @@
+import { l as Storage } from "./types-oAdD2Qlz.mjs";
+
+//#region src/core/storage.d.ts
+type KeychainStorageOptions = {
+  service?: string | undefined;
+  account?: string | undefined; /** Called when a keychain write fails. Use this to surface the error to the user or log it. */
+  onError?: (error: unknown) => void;
+};
+declare function keychainStorage(opts?: KeychainStorageOptions): Promise<Storage>;
+//#endregion
+export { keychainStorage as n, KeychainStorageOptions as t };

package/dist/{types-h9AEfSnq.d.mts → types-oAdD2Qlz.d.mts}

@@ -62,14 +62,10 @@ type DesktopClientOptions = {
   cookiePrefix?: string | string[];
   disableCache?: boolean;
   sanitizeUser?: (user: AuthUser) => Awaitable<AuthUser>;
-  /**
-   * What the loopback shows after a successful exchange. A string is used as the
-   * HTML body; an object can redirect the browser to your own page instead.
-   * Defaults to a built-in "you can close this tab" page.
-   */
   loopbackSuccess?: string | {
     redirectTo: string;
-  };
+  }; /** Called when a keychain/storage write fails. Use this to surface the error to the user or log it. */
+  onStorageError?: (error: unknown) => void;
 };
 //#endregion
 export { LoopbackRequest as a, RequestAuthOptions as c, DesktopClientOptions as i, Storage as l, AuthUser as n, LoopbackResponse as o, DesktopAdapter as r, LoopbackServer as s, AuthEvent as t };

package/dist/{version-1hEssvcU.mjs → version-C6KnA6nF.mjs}

@@ -1,5 +1,5 @@
 //#endregion
 //#region src/version.ts
-const PACKAGE_VERSION = "0.1.0";
+const PACKAGE_VERSION = "0.1.2";
 //#endregion
 export { PACKAGE_VERSION as t };

package/dist/web/index.d.mts

@@ -1,32 +1,50 @@
-//#region src/web/forward-to-desktop.d.ts
+import { n as AuthUser } from "../types-oAdD2Qlz.mjs";
+import { t as AuthBridges } from "../schema-CE7bJ4bb.mjs";
+
+//#region src/web/forward.d.ts
 type ForwardToDesktopOptions = {
-  /** Must match the server plugin's `hashKey`. @default "token" */hashKey?: string;
+  hashKey?: string;
+};
+type ForwardToDesktopResult = {
+  success: true;
+  error: null;
+} | {
+  success: false;
+  error: Error;
 };
 /**
- * Opt-in successor to the old scheme-based `forwardCallback`. On a branded
- * `webCallbackUrl` page, reads `#token=…&loopback=…` from the fragment and
- * performs a **top-level navigation** to the desktop loopback
- * (`http://127.0.0.1:<port>/…?token=…`) — no CORS / PNA / mixed-content.
- *
- * Returns `false` (a no-op) outside a browser or when the fragment is absent,
- * so it is safe to call unconditionally on the callback page.
- */
-declare function forwardToDesktop(options?: ForwardToDesktopOptions): boolean;
-/**
- * Better Auth client plugin wrapping {@link forwardToDesktop}, for consumers
- * that prefer the `createAuthClient({ plugins: [...] })` pattern:
- *
- * ```ts
- * const authClient = createAuthClient({ plugins: [webDesktop()] });
- * authClient.forwardToDesktop();
- * ```
+ * Reads `#token=…&loopback=…` from the URL fragment and navigates to the
+ * desktop loopback URL. Returns `success: false` outside a browser or when
+ * the fragment is absent.
  */
+declare function forwardToDesktop(options?: ForwardToDesktopOptions): ForwardToDesktopResult;
+/** Better-auth client plugin that exposes {@link forwardToDesktop} as a client action. */
 declare const webDesktop: (options?: ForwardToDesktopOptions) => {
   id: "desktop-web";
   version: string;
   getActions: () => {
-    forwardToDesktop: () => boolean;
+    forwardToDesktop: () => ForwardToDesktopResult;
   };
 };
 //#endregion
-export { type ForwardToDesktopOptions, forwardToDesktop, webDesktop };
+//#region src/web/wrap.d.ts
+/**
+ * Session hook compatible with {@link wrapForDesktop}'s third parameter.
+ * Use this to type a custom framework hook (Vue, Svelte, etc.) before passing it in.
+ */
+type UseSessionFn<TUser extends AuthUser = AuthUser> = (bridge: AuthBridges<TUser> | null) => {
+  data: {
+    user: TUser;
+  } | null;
+  isPending: boolean;
+  error: unknown;
+};
+/**
+ * Proxy-wraps a better-auth client so that `getSession`, `signOut`, and
+ * `signIn.social` are delegated to the desktop bridge. Pass an optional
+ * `useSessionFn` to also intercept `useSession`. Returns `base` unchanged
+ * when `bridge` is `null`.
+ */
+declare function wrapForDesktop<T extends object, TUser extends AuthUser = AuthUser>(base: T, bridge: AuthBridges<TUser> | null, useSessionFn?: UseSessionFn<TUser>): T;
+//#endregion
+export { type ForwardToDesktopOptions, type UseSessionFn, forwardToDesktop, webDesktop, wrapForDesktop };

package/dist/web/index.mjs

@@ -1,41 +1,76 @@
-import { t as PACKAGE_VERSION } from "../version-1hEssvcU.mjs";
-import { a as parseLoopbackUrl } from "../loopback-DTQgg1Za.mjs";
-//#region src/web/forward-to-desktop.ts
+import { t as PACKAGE_VERSION } from "../version-C6KnA6nF.mjs";
+import { a as parseLoopbackUrl } from "../loopback-CNOfW74-.mjs";
+//#region src/web/forward.ts
 /**
-* Opt-in successor to the old scheme-based `forwardCallback`. On a branded
-* `webCallbackUrl` page, reads `#token=…&loopback=…` from the fragment and
-* performs a **top-level navigation** to the desktop loopback
-* (`http://127.0.0.1:<port>/…?token=…`) — no CORS / PNA / mixed-content.
-*
-* Returns `false` (a no-op) outside a browser or when the fragment is absent,
-* so it is safe to call unconditionally on the callback page.
+* Reads `#token=…&loopback=…` from the URL fragment and navigates to the
+* desktop loopback URL. Returns `success: false` outside a browser or when
+* the fragment is absent.
 */
 function forwardToDesktop(options) {
-	if (typeof window === "undefined" || !window) return false;
+	if (typeof window === "undefined" || !window) return {
+		success: false,
+		error: /* @__PURE__ */ new Error("Not running in a browser")
+	};
 	const hashKey = options?.hashKey ?? "token";
 	const params = new URLSearchParams(window.location.hash.replace(/^#/, ""));
 	const token = params.get(hashKey);
 	const loopback = params.get("loopback");
-	if (!token || !loopback) return false;
-	const target = parseLoopbackUrl(decodeURIComponent(loopback));
-	if (!target) return false;
+	if (!token || !loopback) return {
+		success: false,
+		error: /* @__PURE__ */ new Error("Missing token or loopback in URL fragment")
+	};
+	const target = parseLoopbackUrl(loopback);
+	if (!target) return {
+		success: false,
+		error: /* @__PURE__ */ new Error("Invalid loopback URL")
+	};
 	target.searchParams.set(hashKey, token);
 	window.location.replace(target.toString());
-	return true;
+	return {
+		success: true,
+		error: null
+	};
 }
-/**
-* Better Auth client plugin wrapping {@link forwardToDesktop}, for consumers
-* that prefer the `createAuthClient({ plugins: [...] })` pattern:
-*
-* ```ts
-* const authClient = createAuthClient({ plugins: [webDesktop()] });
-* authClient.forwardToDesktop();
-* ```
-*/
+/** Better-auth client plugin that exposes {@link forwardToDesktop} as a client action. */
 const webDesktop = (options) => ({
 	id: "desktop-web",
 	version: PACKAGE_VERSION,
 	getActions: () => ({ forwardToDesktop: () => forwardToDesktop(options) })
 });
 //#endregion
-export { forwardToDesktop, webDesktop };
+//#region src/web/wrap.ts
+/**
+* Proxy-wraps a better-auth client so that `getSession`, `signOut`, and
+* `signIn.social` are delegated to the desktop bridge. Pass an optional
+* `useSessionFn` to also intercept `useSession`. Returns `base` unchanged
+* when `bridge` is `null`.
+*/
+function wrapForDesktop(base, bridge, useSessionFn) {
+	if (!bridge) return base;
+	return new Proxy(base, { get(target, prop, receiver) {
+		if (prop === "useSession") {
+			if (useSessionFn) return () => useSessionFn(bridge);
+			return Reflect.get(target, prop, receiver);
+		}
+		if (prop === "getSession") return () => bridge.getSession();
+		if (prop === "signOut") return () => bridge.signOut();
+		if (prop !== "signIn") return Reflect.get(target, prop, receiver);
+		const signIn = Reflect.get(target, prop, receiver);
+		return new Proxy(signIn, { get(signInTarget, signInProp, signInReceiver) {
+			if (signInProp !== "social") return Reflect.get(signInTarget, signInProp, signInReceiver);
+			return (params) => {
+				const { disableRedirect, ...rest } = params;
+				if (disableRedirect) return bridge.getAuthUrl(rest).then((url) => ({
+					data: {
+						url,
+						redirect: false
+					},
+					error: null
+				}));
+				return bridge.requestAuth(rest);
+			};
+		} });
+	} });
+}
+//#endregion
+export { forwardToDesktop, webDesktop, wrapForDesktop };

package/package.json

@@ -1,13 +1,13 @@
 {
 	"name": "@soorya-u/better-auth-desktop",
-	"version": "0.1.0",
+	"version": "0.1.2",
 	"description": "Loopback-based desktop auth for Better Auth. Framework-agnostic server + core with thin Electrobun and Electron adapters; OAuth hand-off via a 127.0.0.1 loopback navigation (no custom URL scheme).",
 	"type": "module",
 	"license": "MIT",
-	"homepage": "https://github.com/soorya-u/better-auth-electrobun",
+	"homepage": "https://github.com/soorya-u/better-auth-desktop",
 	"repository": {
 		"type": "git",
-		"url": "git+https://github.com/soorya-u/better-auth-electrobun.git"
+		"url": "git+https://github.com/soorya-u/better-auth-desktop.git"
 	},
 	"keywords": [
 		"electrobun",
@@ -23,6 +23,7 @@
 	},
 	"sideEffects": false,
 	"scripts": {
+		"prepare": "lefthook install",
 		"build": "tsdown",
 		"dev": "tsdown --watch",
 		"lint:package": "publint run --strict --pack false",
@@ -80,6 +81,11 @@
 			"dev-source": "./src/rpc/webview.ts",
 			"types": "./dist/rpc/webview.d.mts",
 			"default": "./dist/rpc/webview.mjs"
+		},
+		"./react": {
+			"dev-source": "./src/react.ts",
+			"types": "./dist/react.d.mts",
+			"default": "./dist/react.mjs"
 		}
 	},
 	"typesVersions": {
@@ -107,20 +113,23 @@
 			],
 			"rpc/webview": [
 				"./dist/rpc/webview.d.mts"
+			],
+			"react": [
+				"./dist/react.d.mts"
 			]
 		}
 	},
-	"dependencies": {
-		"zod": "^4.3.6"
-	},
 	"devDependencies": {
+		"@arethetypeswrong/cli": "^0.18.4",
 		"@biomejs/biome": "^2.5.1",
 		"@types/better-sqlite3": "^7.6.13",
 		"@types/bun": "latest",
+		"@types/react": "^19.2.17",
 		"better-auth": "^1.6.21",
 		"better-call": "1.3.7",
 		"better-sqlite3": "^12.11.1",
 		"electrobun": "^1.18.1",
+		"lefthook": "^2.1.9",
 		"publint": "^0.3.12",
 		"tsdown": "^0.21.1",
 		"typescript": "^5.9.3",
@@ -128,6 +137,7 @@
 	},
 	"peerDependencies": {
 		"@better-auth/core": "^1.6.21",
+		"react": ">=18.0.0",
 		"@better-auth/utils": "^0.4.2",
 		"@better-fetch/fetch": "^1.3.1",
 		"better-auth": "^1.6.21",
@@ -145,6 +155,9 @@
 		},
 		"electron-store": {
 			"optional": true
+		},
+		"react": {
+			"optional": true
 		}
 	},
 	"engines": {

package/dist/storage-DtgX_vmE.d.mts

@@ -1,10 +0,0 @@
-import { l as Storage } from "./types-h9AEfSnq.mjs";
-
-//#region src/core/storage.d.ts
-type KeychainStorageOptions = {
-  service?: string | undefined;
-  account?: string | undefined;
-};
-declare function keychainStorage(opts?: KeychainStorageOptions): Promise<Storage>;
-//#endregion
-export { keychainStorage as n, KeychainStorageOptions as t };