@bigio/better-auth-electron 1.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bigmusic
+
+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

@@ -0,0 +1,188 @@
+# @bigio/better-auth-electron
+
+> **Work In Progress:** This library is actively being developed. Detailed documentation and architecture diagrams are coming soon.
+
+**A type-safe, IPC-based Better Auth integration for Electron.**
+
+Designed for production-grade applications, this library provides a secure, "batteries-included" solution to integrate [Better Auth](https://www.better-auth.com) into Electron apps without the headache of writing manual IPC bridges or handling complex OAuth window flows.
+
+## Features
+
+- ** Strict Process Isolation:** Zero leakage of server secrets into the Renderer.
+- ** Type-Safe IPC:** Full type inference between Main and Renderer processes.
+- ** React 19 & Preact Compatible:** Solves "Invalid Hook Call" and duplicate instance issues.
+- ** Smart Session Handoff:** Seamlessly transfers authentication states from the web auth flow to the Electron app.
+
+## Installation
+
+```bash
+pnpm add @bigio/better-auth-electron
+```
+
+Ensure peer dependencies are installed:(more framework support coming soon...)
+
+```bash
+pnpm add better-auth electron react react-dom
+```
+
+## Quick Start
+
+### 1. Server Setup (`src/lib/auth.ts`)
+
+Initialize Better Auth with the `electronServerPlugin`. This handles the ticket exchange and verification logic on your backend.
+
+```typescript
+import { betterAuth } from 'better-auth'
+import { electronServerPlugin } from '@bigio/better-auth-electron/server'
+
+export const auth = betterAuth({
+  baseURL: 'http://localhost:3002',
+  // ... your database configuration
+  plugins: [
+    electronServerPlugin({
+      // The custom scheme your Electron app uses (e.g. bigio://)
+      ELECTRON_SCHEME: 'bigio',
+      // Allowed providers for Electron OAuth flow
+      PROVIDERS: ['github', 'google'],
+    }),
+  ],
+  database: {
+    //...
+  },
+})
+```
+
+### 2. Electron Main Process (`src/main/index.ts`)
+
+Use `mainInjection` to setup IPC handlers and deep linking strategies. This automatically handles the "protocol" opening events.
+
+```typescript
+import { app, BrowserWindow } from 'electron'
+import { mainInjection } from '@bigio/better-auth-electron/main'
+
+// Initialize the plugin logic
+const { windowInjection, whenReadyInjection } = mainInjection({
+  isOAuth: true,
+  ELECTRON_APP_NAME: 'bigio-electron-demo',
+  ELECTRON_SCHEME: 'bigio', // Must match the server config
+  PROVIDERS: ['github', 'google'],
+  BETTER_AUTH_BASEURL: 'http://localhost:3002',
+  FRONTEND_URL: 'http://localhost:3001/oauth',
+  // Use the classic 'onBeforeRequest' filter approach for auth code capture
+  OLD_SCHOOL_ONBEFORE_WAY: true,
+})
+
+function createWindow(): void {
+  const mainWindow = new BrowserWindow({
+    /* config */
+  })
+
+  // Inject IPC handlers into the specific window instance
+  windowInjection(mainWindow)
+}
+
+app.whenReady().then(() => {
+  // Register custom protocol schemes and deep link listeners
+  whenReadyInjection()
+  createWindow()
+})
+```
+
+### 3. Web Client Initialization (`src/web/client.ts`)
+
+Configure the client-side plugin. Note the usage of `setLazyClient` to handle circular dependencies or lazy initialization patterns effectively.
+
+```typescript
+import { createAuthClient } from 'better-auth/react'
+import { electronWebHandoffPlugin, setLazyClient } from '@bigio/better-auth-electron/web'
+import type { auth } from '@/lib/auth' // Import type from your server file
+
+export const authClient = createAuthClient({
+  baseURL: 'http://localhost:3002',
+  fetchOptions: {
+    credentials: 'include',
+  },
+  plugins: [
+    // Type-safe plugin initialization
+    electronWebHandoffPlugin<typeof auth>(),
+  ],
+})
+
+// Important: Register the client instance for plugin lazy access, this for soical signin
+setLazyClient(authClient)
+```
+
+### 4. Electron Renderer / Login Page (`src/renderer/pages/login.tsx`)
+
+In your Electron renderer (the UI), use the helper options to construct the correct OAuth URL that opens in the system's default browser.
+
+```typescript
+import type { ElectronButtonOptions } from '@bigio/better-auth-electron/options'
+import { defaultButtonOptions } from '@bigio/better-auth-electron/options'
+
+// Merge default options with any custom overrides
+const config: ElectronButtonOptions = { ...defaultButtonOptions }
+const { FRONTEND_URL, PROVIDER_NAME_IN_URL } = config
+
+const ElectronLoginButton = ({ provider }: { provider: string }) => {
+  const handleOpen = () => {
+    // Construct the auth URL
+    const targetUrl = `${FRONTEND_URL}?${PROVIDER_NAME_IN_URL}=${provider}`
+
+    // Open in external browser (e.g., Chrome/Safari) to start the flow
+    window.open(targetUrl, '_blank')
+    console.log('Opening External Browser for OAuth...')
+  }
+
+  return (
+    <button onClick={handleOpen}>
+      Sign in with {provider}
+    </button>
+  )
+}
+```
+
+### 5. Web/App Component Usage (`src/web/components/user-session.tsx`)
+
+The `useElectronOAuthSession` hook is the heart of the "Handoff" experience. It listens for the deep link callback and automatically verifies the session.
+
+```typescript
+import { authClient } from '@/web/client'
+
+export function UserSessionStatus() {
+  const {
+    // The validated session data (user, session token)
+    data: useSessionData,
+
+    // Any error that occurred during the deep link handoff
+    error,
+
+    // True when the initial check or handoff is in progress
+    isPending,
+
+    // True when explicitly refetching the session state
+    isRefetching,
+
+    // Function to manually re-trigger session validation
+    refetch,
+
+    // Real-time status messages from the main process
+    // (e.g., "Verifying ticket...", "Session established")
+    oauthMessage
+  } = authClient.bigio.useElectronOAuthSession()
+
+  if (isPending) return <div>Loading session... {oauthMessage}</div>
+  if (error) return <div>Error: {error.message}</div>
+
+  return (
+    <div>
+      <h1>Welcome, {useSessionData?.user.name}</h1>
+      <p>Status: {oauthMessage || 'Idle'}</p>
+    </div>
+  )
+}
+```
+
+## License
+
+MIT © [bigmusic](https://github.com/bigmusic/better-auth-electron)

package/dist/main.d.ts

@@ -0,0 +1,10 @@
+import { BrowserWindow } from 'electron';
+import { ElectronMainPluginOptions } from './options.js';
+import 'better-auth';
+
+declare const mainInjection: (options?: ElectronMainPluginOptions) => {
+    windowInjection: (mainWindow: BrowserWindow) => void;
+    whenReadyInjection: () => void;
+};
+
+export { mainInjection };