tauri-plugin-better-auth 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Muhammed Koç and tauri-plugin-better-auth contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,50 @@
-# Temporary Holding Version
+# tauri-plugin-better-auth
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[Better Auth](https://better-auth.com) for [Tauri 2](https://tauri.app). Users
+sign in through the system browser with PKCE. The session lives in Rust, and
+webview code never sees a token.
+
+This npm package is one half of the plugin. The other half is the Rust crate
+[`tauri-plugin-better-auth`](https://crates.io/crates/tauri-plugin-better-auth).
+Full documentation:
+[github.com/laakal/tauri-plugin-better-auth](https://github.com/laakal/tauri-plugin-better-auth#readme).
+
+```sh
+npm install tauri-plugin-better-auth
+```
+
+| Import                            | Where                   | What                                                                  |
+| --------------------------------- | ----------------------- | --------------------------------------------------------------------- |
+| `tauri-plugin-better-auth`        | Your Better Auth server | `tauri()` server plugin: `/tauri/authorize`, `/tauri/token`           |
+| `tauri-plugin-better-auth/proxy`  | Your hand-off web page  | `tauriProxyClient()`: request capture, consent hand-off, cancel       |
+| `tauri-plugin-better-auth/client` | The Tauri webview       | `withTauri()`, `tauriFetch`, `requestAuth()`, events, tokenless types |
+
+```ts
+// Server
+import { bearer } from 'better-auth/plugins';
+import { tauri } from 'tauri-plugin-better-auth';
+betterAuth({
+  plugins: [
+    bearer(),
+    tauri({
+      clientID: 'com.example.app',
+      authorizeOrigins: ['https://example.com'],
+    }),
+  ],
+});
+
+// Tauri webview
+import { createAuthClient } from 'better-auth/react';
+import {
+  asTauriClient,
+  requestAuth,
+  withTauri,
+} from 'tauri-plugin-better-auth/client';
+const authClient = asTauriClient(
+  createAuthClient(withTauri({ baseURL: 'https://api.example.com/api/auth' })),
+);
+await requestAuth();
+```
+
+Requires `better-auth` >= 1.7.4 and, for `/client`, `@tauri-apps/api` >= 2.11.
+MIT licensed.

package/dist/client.d.ts

@@ -0,0 +1,232 @@
+import { UnlistenFn } from "@tauri-apps/api/event";
+import { BetterAuthClientOptions } from "@better-auth/core";
+//#region src/client/commands.d.ts
+/** How the browser hands the sign-in back to the app. */
+type Transport = 'auto' | 'deep-link' | 'loopback';
+/** The signed-in user (Better Auth user object). */
+type TauriUser = Record<string, unknown> & {
+  id: string;
+  email?: string;
+  name?: string;
+  image?: string | null;
+};
+/** The current session as the webview sees it: never contains a token. */
+interface TauriSessionSnapshot<U = TauriUser, S = Record<string, unknown>> {
+  user: U;
+  /** Better Auth session object without `token`. */
+  session: S;
+  /** True when the server could not be reached and this is the cached copy. */
+  offline: boolean;
+}
+interface RequestAuthOptions {
+  /** Social provider the hand-off page should start (if it allows it). */
+  provider?: string;
+  /** Overrides the transport configured in Rust for this sign-in. */
+  transport?: Transport;
+}
+interface RequestAuthResult {
+  /** The sign-in URL: show it when the browser could not be opened. */
+  url: string;
+  /** Whether the system browser was opened. */
+  opened: boolean;
+  /** The transport chosen for this sign-in. */
+  transport: Transport;
+}
+/** Error raised by the plugin commands; `code` is stable (see the README). */
+export declare class TauriAuthError extends Error {
+  readonly code: string;
+  name: string;
+  constructor(code: string, message: string);
+}
+/** True for errors raised by this plugin. */
+export declare function isTauriAuthError(error: unknown): error is TauriAuthError;
+/**
+ * Opens the system browser on your sign-in page. The result arrives later as
+ * an `authenticated` event (deep link or loopback), or through
+ * {@link authenticate} when the user pastes the code.
+ */
+export declare function requestAuth(options?: RequestAuthOptions): Promise<RequestAuthResult>;
+/** Completes a sign-in with a pasted code or callback link. */
+export declare function authenticate<U = TauriUser>(codeOrLink: string): Promise<TauriSessionSnapshot<U>>;
+/** Cancels the sign-in in progress. */
+export declare function cancelAuth(): Promise<void>;
+/**
+ * The current session, verified with the server. With `cachedOnly`, returns
+ * the last known session without a network call (fast, for startup guards).
+ * When the server is unreachable the cached copy comes back with `offline`.
+ */
+export declare function getSession<U = TauriUser>(options?: {
+  cachedOnly?: boolean;
+}): Promise<TauriSessionSnapshot<U> | null>;
+/** Signs out locally (always) and on the server (best effort). */
+export declare function signOut(): Promise<void>;
+//#endregion
+//#region src/client/events.d.ts
+/** Why the user is no longer signed in. */
+type SignOutReason = 'user' | 'revoked' | 'expired';
+/** Payload of the error event. */
+interface TauriAuthErrorEvent {
+  code: string;
+  message: string;
+}
+export declare const EVENT_AUTHENTICATED = "better-auth://authenticated";
+export declare const EVENT_SIGNED_OUT = "better-auth://signed-out";
+export declare const EVENT_ERROR = "better-auth://error";
+/** Fires after every successful sign-in (browser or in-app). */
+export declare function onAuthenticated<U = TauriUser>(callback: (user: U) => void): Promise<UnlistenFn>;
+/** Fires when the session ends: signed out, revoked by the server, or expired. */
+export declare function onSignedOut(callback: (event: {
+  reason: SignOutReason;
+}) => void): Promise<UnlistenFn>;
+/** Fires when a background sign-in (deep link or loopback) fails. */
+export declare function onAuthError(callback: (error: TauriAuthErrorEvent) => void): Promise<UnlistenFn>;
+//#endregion
+//#region src/client/fetch.d.ts
+/**
+ * A `fetch` that sends the request through the plugin's Rust bridge.
+ *
+ * Rust adds the session's bearer token and your app headers, refuses anything
+ * outside the configured auth operations and API routes, never follows
+ * redirects, and strips `set-cookie`/`set-auth-token` from responses. The
+ * webview never sees a token.
+ *
+ * Use it as Better Auth's `customFetchImpl` (see `withTauri`) and as the
+ * `fetch` of your API client. Bodies are buffered (no streaming).
+ */
+export declare const tauriFetch: typeof fetch;
+//#endregion
+//#region src/client/plugin.d.ts
+/**
+ * Better Auth client plugin for the Tauri webview. Refreshes `useSession()`
+ * when a browser sign-in completes or the session ends, and adds
+ * `authClient.tauri.*` actions. Added for you by {@link withTauri}.
+ */
+export declare const tauriClient: () => {
+  id: "tauri";
+  getActions: (_$fetch: import("@better-fetch/fetch").BetterFetch, $store: import("better-auth").ClientStore) => {
+    tauri: {
+      /** Opens the system browser on the sign-in page. */
+      requestAuth: typeof requestAuth;
+      /** Completes a sign-in with a pasted code or link. */
+      authenticate: typeof authenticate;
+      /** Cancels the sign-in in progress. */
+      cancelAuth: typeof cancelAuth;
+      /** The current session from Rust (with offline fallback). */
+      getSession: typeof getSession;
+      /** Signs out locally and on the server. */
+      signOut: typeof signOut;
+    };
+  };
+};
+type PluginsOf<O> = O extends {
+  plugins: infer P extends readonly unknown[];
+} ? P : [];
+/** Options returned by {@link withTauri}. */
+type WithTauri<O extends BetterAuthClientOptions> = Omit<O, 'plugins' | 'fetchOptions' | 'disableDefaultFetchPlugins'> & {
+  plugins: [...PluginsOf<O>, ReturnType<typeof tauriClient>];
+  fetchOptions: Omit<NonNullable<O['fetchOptions']>, 'customFetchImpl'> & {
+    customFetchImpl: typeof tauriFetch;
+  };
+  disableDefaultFetchPlugins: true;
+};
+/**
+ * Adapts Better Auth client options for the Tauri webview. Pass the result to
+ * the `createAuthClient` of your framework.
+ *
+ * - every request goes through the Rust bridge (`tauriFetch`): the token is
+ *   added in Rust and never reaches the page;
+ * - Better Auth's redirect plugin is disabled, so no response can navigate
+ *   the webview away from the app (start social sign-in with
+ *   `authClient.tauri.requestAuth({ provider })` instead);
+ * - `useSession()` refreshes after browser sign-ins and sign-outs.
+ *
+ * @example
+ * ```ts
+ * import { createAuthClient } from 'better-auth/react';
+ * import { emailOTPClient } from 'better-auth/client/plugins';
+ * import { asTauriClient, withTauri } from 'tauri-plugin-better-auth/client';
+ *
+ * export const authClient = asTauriClient(
+ *   createAuthClient(withTauri({ baseURL: 'https://api.example.com/api/auth', plugins: [emailOTPClient()] })),
+ * );
+ * ```
+ */
+export declare function withTauri<O extends BetterAuthClientOptions>(options: O): WithTauri<O>;
+//#endregion
+//#region src/client/types.d.ts
+/**
+ * Types that describe a Better Auth client as it behaves inside a Tauri
+ * webview: sessions carry no token, and only the operations the Rust bridge
+ * allows are present.
+ */
+/** A `{ session, user }` pair without `session.token`. */
+type Tokenless<T> = T extends {
+  session: infer S;
+  user: infer U;
+} ? {
+  session: Omit<S, 'token'>;
+  user: U;
+} : T;
+type TokenlessData<D> = D extends {
+  session: unknown;
+  user: unknown;
+} ? Tokenless<D> : D;
+/** Maps `{ data: … }` (a hook result or a fetch response) to tokenless data. */
+type MapData<T> = T extends {
+  data: infer D;
+} ? Omit<T, 'data'> & {
+  data: TokenlessData<D>;
+} : T;
+/** React/Vue/Svelte hooks are functions; the vanilla client exposes an atom. */
+type MapUseSession<U> = U extends ((...args: infer A) => infer R) ? (...args: A) => MapData<R> : U extends {
+  get(): infer V;
+} ? Omit<U, 'get' | 'value' | 'subscribe' | 'listen'> & {
+  get(): MapData<V>;
+  readonly value: MapData<V> | undefined;
+  subscribe(listener: (value: MapData<V>) => void): () => void;
+  listen(listener: (value: MapData<V>) => void): () => void;
+} : U;
+type MapGetSession<G> = G extends ((...args: infer A) => Promise<infer R>) ? (...args: A) => Promise<MapData<R>> : G;
+type Restrict<T, K extends string> = T extends object ? Pick<T, Extract<keyof T, K>> : never;
+/** Sign-in methods the bridge accepts by default. */
+type TauriSignInMethod = 'email' | 'emailOtp';
+/**
+ * Client actions the bridge refuses: they read or mint credentials, or need
+ * browser redirects. Use `authClient.tauri.requestAuth()` for browser flows.
+ */
+type TauriUnsupportedAction = 'listSessions' | 'revokeSession' | 'revokeSessions' | 'revokeOtherSessions' | 'oneTimeToken' | 'linkSocial' | 'unlinkAccount' | 'getAccessToken' | 'refreshToken' | 'accountInfo' | 'multiSession' | 'token';
+/**
+ * A Better Auth client as seen in the Tauri webview: tokenless sessions,
+ * in-app sign-in limited to `email` and `emailOtp` (plus `ExtraSignIn`, for
+ * routes you allowed in Rust with `Builder::auth_route`).
+ */
+type TauriAuthClient<C, ExtraSignIn extends string = never> = Omit<C, 'useSession' | 'getSession' | 'hydrateSession' | '$Infer' | 'signIn' | 'signUp' | TauriUnsupportedAction> & {
+  useSession: C extends {
+    useSession: infer U;
+  } ? MapUseSession<U> : never;
+  getSession: C extends {
+    getSession: infer G;
+  } ? MapGetSession<G> : never;
+  signIn: C extends {
+    signIn: infer S;
+  } ? Restrict<S, TauriSignInMethod | ExtraSignIn> : never;
+  signUp: C extends {
+    signUp: infer S;
+  } ? Restrict<S, 'email'> : never;
+  $Infer: (C extends {
+    $Infer: infer I;
+  } ? Omit<I, 'Session'> : {}) & {
+    Session: C extends {
+      $Infer: {
+        Session: infer S;
+      };
+    } ? Tokenless<S> : never;
+  };
+};
+/**
+ * Narrows a client created with `withTauri` to {@link TauriAuthClient}.
+ * Runtime no-op: the bridge already enforces all of this.
+ */
+export declare function asTauriClient<C, ExtraSignIn extends string = never>(client: C): TauriAuthClient<C, ExtraSignIn>;
+//#endregion
+export type { RequestAuthOptions, RequestAuthResult, SignOutReason, TauriAuthClient, TauriAuthErrorEvent, TauriSessionSnapshot, TauriSignInMethod, TauriUnsupportedAction, TauriUser, Tokenless, Transport, WithTauri };

package/dist/client.js

@@ -0,0 +1,244 @@
+import { invoke, isTauri } from "@tauri-apps/api/core";
+import { listen } from "@tauri-apps/api/event";
+//#region src/client/commands.ts
+/** Error raised by the plugin commands; `code` is stable (see the README). */
+var TauriAuthError = class extends Error {
+	code;
+	name = "TauriAuthError";
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+	}
+};
+/** True for errors raised by this plugin. */
+function isTauriAuthError(error) {
+	return error instanceof TauriAuthError;
+}
+function toError(error) {
+	if (typeof error === "object" && error !== null && "code" in error && typeof error.code === "string") {
+		const message = "message" in error && typeof error.message === "string" ? error.message : error.code;
+		return new TauriAuthError(error.code, message);
+	}
+	return error instanceof Error ? error : new Error(String(error));
+}
+/** `invoke` for this plugin, with errors mapped to {@link TauriAuthError}. */
+async function call(command, args) {
+	try {
+		return await invoke(`plugin:better-auth|${command}`, args);
+	} catch (error) {
+		throw toError(error);
+	}
+}
+/**
+* Opens the system browser on your sign-in page. The result arrives later as
+* an `authenticated` event (deep link or loopback), or through
+* {@link authenticate} when the user pastes the code.
+*/
+function requestAuth(options = {}) {
+	return call("request_auth", { options });
+}
+/** Completes a sign-in with a pasted code or callback link. */
+function authenticate(codeOrLink) {
+	return call("authenticate", { code: codeOrLink });
+}
+/** Cancels the sign-in in progress. */
+function cancelAuth() {
+	return call("cancel_auth");
+}
+/**
+* The current session, verified with the server. With `cachedOnly`, returns
+* the last known session without a network call (fast, for startup guards).
+* When the server is unreachable the cached copy comes back with `offline`.
+*/
+function getSession(options = {}) {
+	return call("get_session", { cachedOnly: options.cachedOnly ?? false });
+}
+/** Signs out locally (always) and on the server (best effort). */
+function signOut() {
+	return call("sign_out");
+}
+//#endregion
+//#region src/client/events.ts
+const EVENT_AUTHENTICATED = "better-auth://authenticated";
+const EVENT_SIGNED_OUT = "better-auth://signed-out";
+const EVENT_ERROR = "better-auth://error";
+/** Fires after every successful sign-in (browser or in-app). */
+function onAuthenticated(callback) {
+	return listen(EVENT_AUTHENTICATED, (event) => callback(event.payload.user));
+}
+/** Fires when the session ends: signed out, revoked by the server, or expired. */
+function onSignedOut(callback) {
+	return listen(EVENT_SIGNED_OUT, (event) => callback(event.payload));
+}
+/** Fires when a background sign-in (deep link or loopback) fails. */
+function onAuthError(callback) {
+	return listen(EVENT_ERROR, (event) => callback(event.payload));
+}
+//#endregion
+//#region src/client/fetch.ts
+const NULL_BODY_STATUSES = /* @__PURE__ */ new Set([
+	101,
+	204,
+	205,
+	304
+]);
+const MAX_ID = 4294967295;
+let nextId = 1;
+function takeId() {
+	const id = nextId;
+	nextId = nextId >= MAX_ID ? 1 : nextId + 1;
+	return id;
+}
+function isTextual(contentType) {
+	if (!contentType) return false;
+	const value = contentType.toLowerCase();
+	return value.startsWith("text/") || value.includes("json") || value.includes("xml") || value.includes("javascript") || value.includes("x-www-form-urlencoded");
+}
+function toBase64(bytes) {
+	let binary = "";
+	for (let i = 0; i < bytes.length; i += 32768) binary += String.fromCharCode(...bytes.subarray(i, i + 32768));
+	return btoa(binary);
+}
+function fromBase64(data) {
+	const binary = atob(data);
+	const bytes = new Uint8Array(binary.length);
+	for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+	return bytes;
+}
+async function encodeBody(request) {
+	if (request.method === "GET" || request.method === "HEAD") return null;
+	const bytes = new Uint8Array(await request.arrayBuffer());
+	if (bytes.byteLength === 0) return null;
+	if (isTextual(request.headers.get("content-type"))) try {
+		return {
+			encoding: "text",
+			data: new TextDecoder("utf-8", { fatal: true }).decode(bytes)
+		};
+	} catch {}
+	return {
+		encoding: "base64",
+		data: toBase64(bytes)
+	};
+}
+function abortError(signal) {
+	return signal?.reason ?? new DOMException("The operation was aborted.", "AbortError");
+}
+/**
+* A `fetch` that sends the request through the plugin's Rust bridge.
+*
+* Rust adds the session's bearer token and your app headers, refuses anything
+* outside the configured auth operations and API routes, never follows
+* redirects, and strips `set-cookie`/`set-auth-token` from responses. The
+* webview never sees a token.
+*
+* Use it as Better Auth's `customFetchImpl` (see `withTauri`) and as the
+* `fetch` of your API client. Bodies are buffered (no streaming).
+*/
+const tauriFetch = async (input, init) => {
+	const request = new Request(input, init);
+	const signal = init?.signal ?? request.signal;
+	if (signal?.aborted) throw abortError(signal);
+	const id = takeId();
+	const headers = [];
+	request.headers.forEach((value, name) => headers.push([name, value]));
+	const body = await encodeBody(request);
+	const onAbort = () => {
+		invoke("plugin:better-auth|fetch_cancel", { id }).catch(() => {});
+	};
+	signal?.addEventListener("abort", onAbort, { once: true });
+	try {
+		const response = await invoke("plugin:better-auth|fetch", { request: {
+			id,
+			url: request.url,
+			method: request.method,
+			headers,
+			body
+		} });
+		const payload = response.body === null || NULL_BODY_STATUSES.has(response.status) ? null : response.body.encoding === "text" ? response.body.data : fromBase64(response.body.data);
+		return new Response(payload, {
+			status: response.status,
+			statusText: response.statusText,
+			headers: response.headers
+		});
+	} catch (error) {
+		if (signal?.aborted) throw abortError(signal);
+		if ((typeof error === "object" && error !== null && "code" in error ? String(error.code) : void 0) === "ABORTED") throw abortError(signal);
+		const message = typeof error === "object" && error !== null && "message" in error ? String(error.message) : String(error);
+		throw new TypeError(`Failed to fetch: ${message}`, { cause: error });
+	} finally {
+		signal?.removeEventListener("abort", onAbort);
+	}
+};
+//#endregion
+//#region src/client/plugin.ts
+/**
+* Better Auth client plugin for the Tauri webview. Refreshes `useSession()`
+* when a browser sign-in completes or the session ends, and adds
+* `authClient.tauri.*` actions. Added for you by {@link withTauri}.
+*/
+const tauriClient = () => ({
+	id: "tauri",
+	getActions: (_$fetch, $store) => {
+		if (typeof window !== "undefined" && isTauri()) {
+			const refresh = () => $store.notify("$sessionSignal");
+			onAuthenticated(refresh);
+			onSignedOut(refresh);
+		}
+		return { tauri: {
+			/** Opens the system browser on the sign-in page. */
+			requestAuth,
+			/** Completes a sign-in with a pasted code or link. */
+			authenticate,
+			/** Cancels the sign-in in progress. */
+			cancelAuth,
+			/** The current session from Rust (with offline fallback). */
+			getSession,
+			/** Signs out locally and on the server. */
+			signOut
+		} };
+	}
+});
+/**
+* Adapts Better Auth client options for the Tauri webview. Pass the result to
+* the `createAuthClient` of your framework.
+*
+* - every request goes through the Rust bridge (`tauriFetch`): the token is
+*   added in Rust and never reaches the page;
+* - Better Auth's redirect plugin is disabled, so no response can navigate
+*   the webview away from the app (start social sign-in with
+*   `authClient.tauri.requestAuth({ provider })` instead);
+* - `useSession()` refreshes after browser sign-ins and sign-outs.
+*
+* @example
+* ```ts
+* import { createAuthClient } from 'better-auth/react';
+* import { emailOTPClient } from 'better-auth/client/plugins';
+* import { asTauriClient, withTauri } from 'tauri-plugin-better-auth/client';
+*
+* export const authClient = asTauriClient(
+*   createAuthClient(withTauri({ baseURL: 'https://api.example.com/api/auth', plugins: [emailOTPClient()] })),
+* );
+* ```
+*/
+function withTauri(options) {
+	return {
+		...options,
+		disableDefaultFetchPlugins: true,
+		fetchOptions: {
+			...options.fetchOptions,
+			customFetchImpl: tauriFetch
+		},
+		plugins: [...options.plugins ?? [], tauriClient()]
+	};
+}
+//#endregion
+//#region src/client/types.ts
+/**
+* Narrows a client created with `withTauri` to {@link TauriAuthClient}.
+* Runtime no-op: the bridge already enforces all of this.
+*/
+function asTauriClient(client) {
+	return client;
+}
+//#endregion
+export { EVENT_AUTHENTICATED, EVENT_ERROR, EVENT_SIGNED_OUT, TauriAuthError, asTauriClient, authenticate, cancelAuth, getSession, isTauriAuthError, onAuthError, onAuthenticated, onSignedOut, requestAuth, signOut, tauriClient, tauriFetch, withTauri };