@soorya-u/better-auth-desktop 0.1.0

package/README.md

@@ -0,0 +1,257 @@
+# @soorya-u/better-auth-desktop
+
+Loopback-based desktop authentication for [Better Auth](https://better-auth.com).
+
+OAuth completes in the **system browser** and the resulting session is handed
+back to the desktop app through a **`127.0.0.1` loopback** the app briefly
+listens on — reached by a **top-level browser navigation**, not a custom URL
+scheme. That works on **macOS, Linux, and Windows** with **no OS scheme
+registration**, and avoids the CORS / Private-Network-Access / mixed-content
+problems a `fetch`-based hand-off would hit.
+
+A framework-agnostic **server plugin** and **core** drive the flow; thin
+adapters bind it to a runtime. **Electrobun** ships today; **Electron** is a
+drop-in (it never loads any Electrobun code).
+
+## How it works
+
+```
+WebView (renderer)        Desktop main process            Better Auth server
+   │ requestAuth(github) ─────▶│                                  │
+   │                           │ bind 127.0.0.1:<port>            │
+   │                           │ openExternal(                    │
+   │                           │   /desktop/init-oauth-proxy       │
+   │                           │   ?provider&pkce&callbackURL=http://127.0.0.1:<port>/callback?nonce=N)
+   │                           │                                  │
+ [ system browser ] ── OAuth ──▶ provider ──▶ server callback ──▶ session established
+   │                           │                       /desktop/oauth-complete:
+   │                           │                         mint one-time code; 302 →
+   │                           │                         http://127.0.0.1:<port>/callback?nonce=N&token=T
+ [ system browser ] ── navigates to 127.0.0.1:<port>/callback?token=T&nonce=N
+   │                           │ loopback handler:                │
+   │                           │  verify nonce                    │
+   │                           │  exchange T ────────────────────▶│ /desktop/token (PKCE verify)
+   │                           │  ◀── session ────────────────────│
+   │                           │  store session (keychain)        │
+   │◀── onAuthenticated ───────┤  "you can close this tab"        │
+   │  navigate("/app")         │  close loopback                  │
+```
+
+The one-time code in the loopback URL is **single-use** and **PKCE-bound** (the
+verifier never leaves the desktop), the listener binds **`127.0.0.1` only**, the
+request must carry the matching **nonce**, and the loopback closes after success
+or a timeout. Works in dev (with `oAuthProxy` bouncing through
+`/oauth-proxy-callback`) and prod (direct callback) alike.
+
+## Installation
+
+```bash
+bun add better-auth @soorya-u/better-auth-desktop
+```
+
+## Server
+
+Add the plugin to your Better Auth server. Compose it with `oAuthProxy` if your
+desktop/web origins differ from the OAuth-registered callback origin.
+
+```ts
+// server/auth.ts
+import { betterAuth } from "better-auth";
+import { betterAuthDesktop } from "@soorya-u/better-auth-desktop/server";
+import { oAuthProxy } from "better-auth/plugins";
+
+export const auth = betterAuth({
+  socialProviders: {
+    github: {
+      clientId: process.env.OAUTH_GITHUB_CLIENT_ID!,
+      clientSecret: process.env.OAUTH_GITHUB_CLIENT_SECRET!,
+    },
+  },
+  plugins: [
+    betterAuthDesktop({ clientID: "my-desktop-app" }),
+    oAuthProxy(),
+  ],
+});
+```
+
+### Server options
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `clientID` | `"desktop"` | Must match the desktop adapter's `clientID`. |
+| `codeExpiresIn` | `300` | One-time-code TTL (seconds). |
+| `hashKey` | `"token"` | Name of the one-time-code parameter. |
+| `webCallbackUrl` | — | Optional branded callback page (see below). Omit for the default direct-to-loopback redirect. |
+| `allowedLoopbackPorts` | — | Optional hardening: `number[]` or `{ min, max }`. Restricts which loopback port the server will redirect to. |
+| `disableOriginOverride` | `false` | Disable rewriting the request origin from the `desktop-origin` header. |
+
+By **default** the server redirects the browser straight to the desktop
+loopback. No web callback page is involved.
+
+## Electrobun (desktop)
+
+`electrobunDesktop` is a standard Better Auth client plugin. Use it with
+`createAuthClient` in the Bun **main** process, pass `createBunRPC()` to your
+`BrowserWindow`, and call `setupMain()`.
+
+`storage` is **required** — pass `keychainStorage()` (Bun.secrets) or your own
+keychain-backed `Storage`. The package never picks a default, so it can't
+silently land on a runtime-inappropriate one.
+
+```ts
+// desktop/bun/auth.ts
+import { createAuthClient } from "better-auth/client";
+import {
+  electrobunDesktop,
+  keychainStorage,
+} from "@soorya-u/better-auth-desktop/electrobun";
+
+export const authClient = createAuthClient({
+  baseURL: process.env.SERVER_URL!,
+  plugins: [
+    electrobunDesktop({
+      clientID: "my-desktop-app",
+      storage: await keychainStorage(),
+      // loopbackPort: 51789,  // optional; omit to bind 127.0.0.1:0 (OS-assigned)
+    }),
+  ],
+});
+
+// Bun-side RPC the WebView calls; pass to `new BrowserWindow({ rpc })`.
+export const authBunRpc = authClient.createBunRPC();
+```
+
+```ts
+// desktop/bun/index.ts
+import { BrowserWindow } from "electrobun/bun";
+import { authClient, authBunRpc } from "./auth";
+
+new BrowserWindow({ title: "My App", url, rpc: authBunRpc });
+await authClient.setupMain();
+```
+
+### Renderer (WebView)
+
+```ts
+// renderer entry
+import { defineAuthWebviewRPC } from "@soorya-u/better-auth-desktop/rpc/webview";
+
+export const auth = defineAuthWebviewRPC();
+
+auth.onAuthenticated((user) => navigate("/app"));
+await auth.requestAuth({ provider: "github" });
+```
+
+The bridge exposes `requestAuth`, `getUser`, `signOut`, `getUserImage`, and the
+`onAuthenticated` / `onUserUpdated` / `onAuthError` subscriptions.
+
+No `urlSchemes` / `protocol` registration is needed in `electrobun.config.ts`.
+
+## Electron (desktop)
+
+The Electron adapter shares the same core; it pulls in **no** Electrobun code.
+`storage` is **required**. The package ships `electronStorage()` — persistent
+via [`electron-store`](https://github.com/sindresorhus/electron-store) (install
+it: `bun add electron-store`) with values encrypted by Electron `safeStorage`
+(OS keychain) when available — or you can supply your own `Storage`.
+
+```ts
+// main process
+import { createAuthClient } from "better-auth/client";
+import {
+  electronDesktop,
+  electronStorage,
+} from "@soorya-u/better-auth-desktop/electron";
+
+const authClient = createAuthClient({
+  baseURL: process.env.SERVER_URL!,
+  plugins: [
+    electronDesktop({
+      clientID: "my-desktop-app",
+      getWindow: () => mainWindow,
+      storage: await electronStorage(),
+    }),
+  ],
+});
+await authClient.setupMain();
+```
+
+The renderer talks to it over IPC; the channel names are exported as
+`ELECTRON_AUTH_CHANNELS` from `@soorya-u/better-auth-desktop/electron`.
+
+## Optional: branded web callback page
+
+If you set `webCallbackUrl` on the server plugin, `oauth-complete` redirects the
+browser to your page (`#token=…&loopback=…`) instead of straight to the
+loopback. Your page calls `forwardToDesktop()`, which performs the top-level
+navigation to `127.0.0.1` — still no CORS / PNA / mixed-content.
+
+It's available both as a standalone function and as a Better Auth client plugin:
+
+```ts
+// standalone
+import { forwardToDesktop } from "@soorya-u/better-auth-desktop/web";
+forwardToDesktop(); // safe no-op outside a desktop sign-in
+
+// or as a plugin
+import { webDesktop } from "@soorya-u/better-auth-desktop/web";
+const authClient = createAuthClient({ plugins: [webDesktop()] });
+authClient.forwardToDesktop();
+```
+
+### Customizing the loopback success page
+
+By default the loopback serves a minimal "you can close this tab" page. Override
+it via `loopbackSuccess` on the desktop plugin — a string is used as the HTML
+body, or `{ redirectTo }` bounces the browser to your own page:
+
+```ts
+electrobunDesktop({
+  storage: await keychainStorage(),
+  loopbackSuccess: { redirectTo: "https://app.example.com/signed-in" },
+});
+```
+
+## Custom adapters
+
+`@soorya-u/better-auth-desktop/core` exposes the framework-agnostic pieces —
+the `DesktopAdapter` interface, `startAuthFlow`, `exchangeToken`, the loopback
+helpers, and `desktopClient` — so you can target another runtime. An adapter
+only has to:
+
+```ts
+type DesktopAdapter = {
+  openExternal(url: string): void | Promise<void>;
+  serveLoopback(
+    onRequest: (req: LoopbackRequest) => Promise<LoopbackResponse>,
+    opts?: { port?: number },
+  ): Promise<{ port: number; close(): void }>;
+  notifyRenderer(event: AuthEvent): void;
+  storage: Storage;
+};
+```
+
+## Exports
+
+| Subpath | Purpose |
+| --- | --- |
+| `@soorya-u/better-auth-desktop` | re-exports `core` (types & utilities) |
+| `@soorya-u/better-auth-desktop/server` | `betterAuthDesktop()` server plugin |
+| `@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/client` | `desktopClient()` Better Auth client plugin |
+| `@soorya-u/better-auth-desktop/core` | shared types & utilities for custom adapters |
+
+## Security notes
+
+- The loopback binds `127.0.0.1` only and is unreachable off-box.
+- The token in the loopback URL is a one-time, short-TTL, PKCE-bound code; the
+  verifier never leaves the desktop, so interception/replay is useless.
+- The nonce stops a different local app from consuming the redirect.
+- The loopback closes immediately after a successful exchange (or on timeout).
+
+## License
+
+MIT

package/dist/adapters/electrobun.d.mts

@@ -0,0 +1,49 @@
+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 * as _$_better_fetch_fetch0 from "@better-fetch/fetch";
+import { BetterFetch } from "@better-fetch/fetch";
+import { BetterAuthClientOptions, ClientStore } from "@better-auth/core";
+
+//#region src/adapters/electrobun.d.ts
+type AuthSender = {
+  onAuthenticated(user: AuthUser): void;
+  onUserUpdated(user: AuthUser | null): void;
+  onAuthError(payload: {
+    error: {
+      message: string;
+    };
+    path?: string;
+  }): void;
+};
+type ElectrobunDesktopRPC = {
+  send: AuthSender;
+  setTransport(transport: unknown): void;
+};
+type ElectrobunDesktopOptions = DesktopClientPluginOptions;
+/**
+ * Better Auth client plugin for Electrobun (Bun main process). Use it with
+ * `createAuthClient`, then pass `createBunRPC()` to your `BrowserWindow` and
+ * call `setupMain()`:
+ *
+ * ```ts
+ * const authClient = createAuthClient({
+ *   baseURL,
+ *   plugins: [electrobunDesktop({ clientID, storage: await keychainStorage() })],
+ * });
+ * new BrowserWindow({ rpc: authClient.createBunRPC(), url });
+ * await authClient.setupMain();
+ * ```
+ */
+declare const electrobunDesktop: (options: ElectrobunDesktopOptions) => {
+  id: "desktop";
+  version: string;
+  fetchPlugins: _$_better_fetch_fetch0.BetterFetchPlugin[];
+  getActions: ($fetch: BetterFetch, $store: ClientStore, clientOptions: BetterAuthClientOptions | undefined) => {
+    getCookie: () => string;
+    createBunRPC: () => ElectrobunDesktopRPC;
+    setupMain: () => Promise<() => void | undefined>;
+  };
+};
+//#endregion
+export { ElectrobunDesktopOptions, ElectrobunDesktopRPC, type KeychainStorageOptions, electrobunDesktop, keychainStorage };

package/dist/adapters/electrobun.mjs

@@ -0,0 +1,166 @@
+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 { BrowserView, Utils } from "electrobun/bun";
+//#region src/adapters/electrobun.ts
+function createLoopbackAdapter(getSender, storage) {
+	return {
+		openExternal(url) {
+			if (!Utils.openExternal(url)) throw new Error(`Failed to open the system browser: ${url}`);
+		},
+		async serveLoopback(onRequest, opts) {
+			const server = Bun.serve({
+				hostname: "127.0.0.1",
+				port: opts?.port ?? 0,
+				async fetch(req) {
+					const url = new URL(req.url);
+					const query = {};
+					url.searchParams.forEach((value, key) => {
+						query[key] = value;
+					});
+					const res = await onRequest({
+						path: url.pathname,
+						query
+					});
+					return new Response(res.body, {
+						status: res.status,
+						headers: res.headers
+					});
+				}
+			});
+			return {
+				port: server.port ?? 0,
+				close: () => void server.stop()
+			};
+		},
+		notifyRenderer(event) {
+			const send = getSender();
+			if (!send) return;
+			switch (event.type) {
+				case "authenticated":
+					send.onAuthenticated(event.user);
+					break;
+				case "user-updated":
+					send.onUserUpdated(event.user);
+					break;
+				case "error":
+					send.onAuthError({
+						error: { message: event.error.message },
+						path: event.path
+					});
+					break;
+			}
+		},
+		storage
+	};
+}
+/**
+* Better Auth client plugin for Electrobun (Bun main process). Use it with
+* `createAuthClient`, then pass `createBunRPC()` to your `BrowserWindow` and
+* call `setupMain()`:
+*
+* ```ts
+* const authClient = createAuthClient({
+*   baseURL,
+*   plugins: [electrobunDesktop({ clientID, storage: await keychainStorage() })],
+* });
+* new BrowserWindow({ rpc: authClient.createBunRPC(), url });
+* await authClient.setupMain();
+* ```
+*/
+const electrobunDesktop = (options) => {
+	const layer = createDesktopCookieLayer(options);
+	let rpc = null;
+	const adapter = createLoopbackAdapter(() => rpc?.send ?? null, options.storage);
+	const sanitizeUser = async (user) => {
+		if (user !== null && typeof options.sanitizeUser === "function") try {
+			return await options.sanitizeUser(user);
+		} catch (error) {
+			console.error("Error while sanitizing user", error);
+			return null;
+		}
+		return user;
+	};
+	return {
+		id: "desktop",
+		version: PACKAGE_VERSION,
+		fetchPlugins: [layer.fetchPlugin],
+		getActions: ($fetch, $store, clientOptions) => {
+			layer.bindStore($store);
+			layer.bindServerOrigin(clientOptions?.baseURL);
+			const getCookie = layer.getCookie;
+			const requests = {
+				requestAuth: async ({ options: cfg }) => {
+					await startAuthFlow({
+						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",
+						headers: {
+							cookie: getCookie(),
+							"content-type": "application/json"
+						}
+					})).data?.user ?? null);
+				},
+				signOut: async () => {
+					await $fetch("/sign-out", {
+						method: "POST",
+						body: "{}",
+						headers: {
+							cookie: getCookie(),
+							"content-type": "application/json"
+						}
+					});
+				},
+				getUserImage: async ({ url }) => {
+					const result = await fetchUserImage(clientOptions?.baseURL, url);
+					if (!result) return { dataUrl: null };
+					const { base64 } = await import("@better-auth/utils/base64");
+					return { dataUrl: `data:${result.mimeType};base64,${base64.encode(result.bytes)}` };
+				}
+			};
+			return {
+				getCookie,
+				createBunRPC: () => {
+					rpc = BrowserView.defineRPC({
+						maxRequestTime: 3e4,
+						handlers: {
+							requests,
+							messages: {}
+						}
+					});
+					return rpc;
+				},
+				setupMain: async () => {
+					const unsub = $store.atoms.session?.subscribe(async (state) => {
+						if (state.isPending === true) return;
+						const user = await sanitizeUser(state.data?.user ?? null);
+						adapter.notifyRenderer({
+							type: "user-updated",
+							user
+						});
+					});
+					return () => unsub?.();
+				}
+			};
+		}
+	};
+};
+//#endregion
+export { electrobunDesktop, keychainStorage };

package/dist/adapters/electron.d.mts

@@ -0,0 +1,55 @@
+import { l as Storage } from "../types-h9AEfSnq.mjs";
+import { n as DesktopClientPluginOptions } from "../client-De_zQzE1.mjs";
+import * as _$_better_fetch_fetch0 from "@better-fetch/fetch";
+import { BetterFetch } from "@better-fetch/fetch";
+import { BetterAuthClientOptions, ClientStore } from "@better-auth/core";
+
+//#region src/adapters/electron.d.ts
+declare const ELECTRON_AUTH_CHANNELS: {
+  readonly requestAuth: "desktop:requestAuth";
+  readonly getUser: "desktop:getUser";
+  readonly signOut: "desktop:signOut";
+  readonly getUserImage: "desktop:getUserImage";
+  readonly onAuthenticated: "desktop:onAuthenticated";
+  readonly onUserUpdated: "desktop:onUserUpdated";
+  readonly onAuthError: "desktop:onAuthError";
+};
+type WebContents = {
+  send(channel: string, payload: unknown): void;
+};
+type ElectronWindowLike = {
+  webContents: WebContents;
+} | null | undefined;
+type ElectronStorageOptions = {
+  /** electron-store file name (without extension). @default "better-auth-desktop" */name?: string; /** Encrypt values with Electron `safeStorage` (OS keychain) when available. @default true */
+  encrypt?: boolean;
+};
+declare function electronStorage(opts?: ElectronStorageOptions): Promise<Storage>;
+type ElectronDesktopOptions = DesktopClientPluginOptions & {
+  /** Returns the focused window whose renderer should receive auth events. */getWindow: () => ElectronWindowLike;
+};
+/**
+ * Better Auth client plugin for Electron (main process). Shares the same core
+ * as the Electrobun plugin; pulls in **no** Electrobun code. Use it with
+ * `createAuthClient`, then call `setupMain()` (which registers the IPC handlers
+ * and the session subscription, and returns a cleanup function):
+ *
+ * ```ts
+ * const authClient = createAuthClient({
+ *   baseURL,
+ *   plugins: [electronDesktop({ clientID, storage: await electronStorage(), getWindow })],
+ * });
+ * await authClient.setupMain();
+ * ```
+ */
+declare const electronDesktop: (options: ElectronDesktopOptions) => {
+  id: "desktop";
+  version: string;
+  fetchPlugins: _$_better_fetch_fetch0.BetterFetchPlugin[];
+  getActions: ($fetch: BetterFetch, $store: ClientStore, clientOptions: BetterAuthClientOptions | undefined) => {
+    getCookie: () => string;
+    setupMain: () => Promise<() => void>;
+  };
+};
+//#endregion
+export { ELECTRON_AUTH_CHANNELS, ElectronDesktopOptions, ElectronStorageOptions, electronDesktop, electronStorage };