@bigio/better-auth-electron 1.0.4 → 1.0.5

package/README.md

@@ -1,4 +1,82 @@
-## I'm currently studying the official implementation; the documentation is still rough but will be improved soon. I'm eager and looking forward to exchanging ideas with everyone.
+# @bigio/better-auth-electron
+
+This plugin establishes a secure, **event-driven** authentication bridge between Electron and Better Auth. It treats the system browser strictly as a **stateless transport layer**, utilizing **AES-encrypted tickets** and **PKCE verification** to perform session handoff without persisting web cookies in the desktop environment.
+
+The renderer implementation abandons traditional redirect handling in favor of an IPC-based subscription model (`onDeepLink*`). It features a built-in **cold-start buffer** to guarantee token capture even if the deep link triggers the application before the UI is fully mounted. The API surface is designed to mirror the official Better Auth client patterns, ensuring strict typing and zero-friction integration.
+
+### Key Architecture
+
+- **Stateless Web Handoff**: The browser authenticates via OAuth but does not share the session with Electron. It passes an encrypted, time-limited ticket back to the desktop app.
+- **Security**: Full PKCE flow (Proof Key for Code Exchange) with verified challenges and AES-encrypted exchange tickets.
+- **Event-Driven Renderer**: No page reloads or router redirects. Listen for `onDeepLinkSuccess`, `onDeepLinkNewUser`, or `onDeepLinkFailed` directly within your React/Vue components.
+- **Cold Start Support**: Includes an internal IPC buffer to cache deep link events that occur during the application boot phase, ensuring no authentication intent is lost while the renderer initializes.
+- **API Parity**: Extends the `authClient` with a `bigio` namespace that mimics standard Better Auth methods (e.g., `signInSocial`).
+- **Native Secure Context & Origin Fix:** Leverages `protocol.registerSchemesAsPrivileged` to treat your custom scheme as a secure context. This solves the infamous `Origin` header mismatch and enables `SameSite` cookies to work natively without hacks.
+
+#### _I'm currently studying the official implementation; the documentation is still rough but will be improved soon. I'm eager and looking forward to exchanging ideas with everyone._
+
+# Authentication Flow
+
+The following diagram illustrates the complete OAuth authorization and session handoff process, including the interaction with external **OAuth Providers** (e.g., GitHub, Google):
+
+```mermaid
+sequenceDiagram
+    participant User as User
+    participant E_R as Electron Renderer
+    participant E_M as Electron Main
+    participant Browser as External Browser (Web Frontend)
+    participant Server as Auth Server (Better Auth)
+    participant Provider as OAuth Provider (GitHub/Google)
+
+    Note over E_R, E_M: 1. Initialization & Startup
+    E_R->>E_M: Send App Mounted Signal
+    User->>E_R: Click Login
+    E_R->>E_R: Click Login (window.open)
+    E_M->>E_M: Intercept Request, Generate PKCE Verifier
+    E_M->>Browser: Open External Browser (with Challenge)
+
+    Note over Browser, Provider: 2. Web Handoff Decision & OAuth Flow
+    alt Session Exists
+        Browser->>Browser: Detect Active Session
+        Browser->>User: Show "Continue as [User]" or "Switch Account"
+        alt User selects "Fast Login"
+            User->>Browser: Click "Continue as [User]"
+            Browser->>Server: Request Fast Ticket (POST /fast-ticket)
+            Server->>Server: Generate Encrypted Ticket
+            Server-->>Browser: Return Redirect URL (bigio://...)
+        else User selects "Switch Account"
+            User->>Browser: Click "Switch Account"
+            Browser->>Server: Initiate OAuth (signIn.social)
+            Server->>Provider: Redirect to Provider Login
+            Provider->>User: Prompt for Credentials
+            User->>Provider: Authorize App
+            Provider-->>Server: Callback with Code/Token
+            Note right of Server: Stateless: Set-Cookie is intercepted/removed
+            Server->>Server: Auth Success, Generate Encrypted Ticket
+            Server-->>Browser: Redirect to bigio://callback?ticket=...
+        end
+    else No Session
+        User->>Browser: Select Provider
+        Browser->>Server: Initiate OAuth (signIn.social)
+        Server->>Provider: Redirect to Provider Login
+        Provider->>User: Prompt for Credentials
+        User->>Provider: Authorize App
+        Provider-->>Server: Callback with Code/Token
+        Note right of Server: Stateless: Set-Cookie is intercepted/removed
+        Server->>Server: Auth Success, Generate Encrypted Ticket
+        Server-->>Browser: Redirect to bigio://callback?ticket=...
+    end
+
+    Note over Browser, E_R: 3. Session Handoff
+    Browser->>E_M: Trigger Deep Link (Custom Protocol)
+    E_M->>E_R: Send Ticket & Verifier via IPC
+    E_R->>E_R: Verify PKCE Challenge
+    E_R->>Server: POST /exchange-ticket (Ticket + Verifier)
+    Server->>Server: Decrypt Ticket, Verify PKCE
+    Server->>Server: Create Electron-specific Session
+    Server-->>E_R: Return Session Cookie (SameSite=None)
+    E_R->>E_R: Login Success, Refresh UI
+```
 
 Based on my study of the official implementation code, I have decided on the following to-do list:
 
@@ -24,36 +102,13 @@ Based on my study of the official implementation code, I have decided on the fol
 
 **3. Developer Experience (DX) & API**
 
-- [ ] **Enhanced Renderer API**: Refactor `getActions` to introduce a dedicated `authClient.bigio` namespace.
-- _Feature_: Implement `authClient.bigio.signIn({ provider: 'github' })` wrapper.
-- _Implementation_: Utilize `window.open` (intercepted by Main) or IPC to trigger the flow, keeping the API consistent with the official web client style.
+- [done] ~~**Enhanced Renderer API**: Refactor `getActions` to introduce a dedicated `authClient.bigio` namespace.~~
+- ~~_Feature_: Implement `authClient.bigio.signIn({ provider: 'github' })` wrapper.~~
+- ~~_Implementation_: Utilize `window.open` (intercepted by Main) or IPC to trigger the flow, keeping the API consistent with the official web client style.~~
 
 - [done] ~~**Smart Web Handoff UI (Optional/Next)**: Update the web-side confirmation page to detect and display the currently logged-in web user, offering a "Continue as [User]" button for a seamless transition.~~
 
-# @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-Event 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
-
-- ** Native Secure Context & Origin Fix:**
-  Leverages `protocol.registerSchemesAsPrivileged` to treat your custom scheme as a secure context. This solves the infamous `Origin` header mismatch and enables `SameSite` cookies to work natively without hacks.
-
-- ** Secure PKCE Flow:**
-  Implements the standard **Proof Key for Code Exchange** protocol out-of-the-box. Ensures enterprise-grade security for your OAuth exchanges without exposing secrets.
-
-- ** Preact SSR Coming soon:**
-  Includes a dedicated, lightweight Preact entry point optimized for Server-Side Rendering (SSR) in login windows.
-  _(React 19 supported. Vue/Svelte support coming soon!)_
-
-- ** Zero-IPC Session Handoff:**
-  Uses secure custom protocol deep links to transfer authentication states. Full TypeScript inference via Better Auth plugins — **no fragile IPC bridges** or manual message handling required.
-
-## Installation
+# Installation
 
 ```bash
 pnpm add @bigio/better-auth-electron
@@ -65,7 +120,7 @@ Ensure peer dependencies are installed:(more framework support coming soon...)
 pnpm add better-auth electron react react-dom
 ```
 
-## Quick Start
+# Quick Start
 
 ### 1. Server Setup (`src/lib/auth.ts`)
 
@@ -226,36 +281,124 @@ export const authClient = createAuthClient({
 })
 ```
 
-### 5. Electron Renderer / Login Page (`src/renderer/pages/login.tsx`)
+### 5. Electron Renderer Integration (New API)
 
-In your Electron renderer (the UI), use the helper options to construct the correct OAuth URL that opens in the system's default browser.
+I have refactored the client-side integration to closely mirror the official Better Auth API structure, while adapting it for the specific constraints of the Electron environment (IPC & Deep Linking).
 
-```typescript
-import type { ElectronButtonOptions } from '@bigio/better-auth-electron/options'
-import { defaultButtonOptions } from '@bigio/better-auth-electron/options'
+### Key Features
 
-// Merge default options with any custom overrides
-const config: ElectronButtonOptions = { ...defaultButtonOptions }
-const { FRONTEND_URL, PROVIDER_NAME_IN_URL } = config
+- **Official API Parity:** Uses a syntax similar to `authClient.signIn.social`.
+- **Callback Functions over URLs:** Instead of handling redirects, we use event subscriptions (`onDeepLinkSuccess`, `onDeepLinkNewUser`) to handle the authentication result.
+- **Cold Start Support:** The plugin includes an internal buffer. If the application is opened via a Deep Link before the UI is fully mounted, the plugin caches the session data and triggers the callback immediately upon registration.
 
-const ElectronLoginButton = ({ provider }: { provider: string }) => {
-  const handleOpen = () => {
-    // Construct the auth URL
-    const targetUrl = `${FRONTEND_URL}?${PROVIDER_NAME_IN_URL}=${provider}`
+### Implementation
 
-    // Open in external browser (e.g., Chrome/Safari) to start the flow
-    window.open(targetUrl, '_blank')
-    console.log('Opening External Browser for OAuth...')
-  }
+In your Electron renderer (e.g., `src/renderer/pages/login.tsx`), use the `bigio` namespace exposed by the client plugin.
 
-  return (
-    <button onClick={handleOpen}>
-      Sign in with {provider}
-    </button>
-  )
+#### 1. Triggering the Sign-In
+
+Use `signInSocial` to initiate the flow. This handles the construction of the OAuth URL, serialization of scopes/parameters, and automatically opens the system default browser.
+
+**Note on Constraints:**
+
+1. **`disableRedirect`** is forced to `false`. The flow _must_ redirect to the deep link scheme to trigger the Electron app.
+2. **`additionalData`** is **JSON serialized and encoded into the URL**. Do not pass sensitive data or large objects, as they may hit browser URL length limits.
+
+```tsx
+import { authClient } from '@/lib/auth-client' // Your initialized client
+
+// ... inside your component
+;<button
+  onClick={async () => {
+    await authClient.bigio.signInSocial({
+      // [Required] The provider key (e.g., 'github', 'google')
+      provider: 'github',
+
+      // [Optional] Array of OAuth scopes
+      scopes: ['repo', 'user'],
+
+      // [Optional] Object passed to the backend (JSON serialized via URL)
+      // Warning: Keep this payload small to avoid URL length issues.
+      additionalData: {
+        theme: 'dark',
+        ref_source: 'desktop_app',
+      },
+
+      // [Optional] Hint for the provider (e.g., email address)
+      loginHint: 'user@example.com',
+
+      // [Optional] Force a sign-up screen instead of sign-in
+      requestSignUp: false,
+    })
+  }}>
+  Sign in with GitHub
+</button>
+```
+
+#### 2. Handling the Callback (Deep Link)
+
+Instead of a page redirect, we listen for IPC completion events. You **must** register listeners for success, failure, and (optionally) new user creation.
+
+These functions return an **unsubscribe** handler. You are responsible for cleaning this up to prevent memory leaks or double-firing events.
+
+```tsx
+import { useEffect } from 'react'
+import { useNavigate } from 'react-router-dom'
+import { authClient } from '@/lib/auth-client'
+
+export default function LoginPage() {
+    const navigate = useNavigate()
+
+    useEffect(() => {
+        // 1. Handle Successful Login (Returning User)
+        const unsubscribeSuccess = authClient.bigio.onDeepLinkSuccess(async (data) => {
+            console.log('Login Successful:', data)
+            // data contains { user, session }
+            navigate('/dashboard')
+            return true
+        })
+
+        // 2. Handle New User Registration (First Time Login)
+        // If not provided, 'onDeepLinkSuccess' might be triggered depending on backend config,
+        // but it is recommended to handle new users explicitly if you have an onboarding flow.
+        const unsubscribeNewUser = authClient.bigio.onDeepLinkNewUser(async (data) => {
+             console.log('New User Registered:', data)
+             // data contains { user, session }
+             navigate('/onboarding')
+             return true
+        })
+
+        // 3. Handle Errors (Network issues, User denied access, Invalid State)
+        const unsubscribeError = authClient.bigio.onDeepLinkFailed(async (error) => {
+            console.error('Authentication Failed:', error)
+            // Show toast or error message
+        })
+
+        // Cleanup: Essential for React's StrictMode and component unmounting
+        return () => {
+            unsubscribeSuccess()
+            unsubscribeNewUser()
+            unsubscribeError()
+        }
+    }, [])
+
+    return (
+        // ... your JSX
+    )
 }
+
 ```
 
+### API Reference: `signInSocial`
+
+| Parameter        | Type                      | Description                                                        |
+| ---------------- | ------------------------- | ------------------------------------------------------------------ |
+| `provider`       | `string`                  | **Required.** The key of the provider (e.g., `github`).            |
+| `scopes`         | `string[]`                | **Optional.** Additional OAuth scopes to request.                  |
+| `additionalData` | `Record<string, unknown>` | **Optional.** Metadata sent to the backend. **Serialized to URL.** |
+| `loginHint`      | `string`                  | **Optional.** Passes a hint (usually email) to the provider.       |
+| `requestSignUp`  | `boolean`                 | **Optional.** Hints the provider to show the registration page.    |
+
 ### 6. Web/App Component Usage (`src/web/components/user-session.tsx`)
 
 The `useElectronOAuthSession` hook is the core of the "Handoff" experience. It manages the synchronization between the web authentication state and the Electron application.

package/dist/main.js

@@ -3,7 +3,7 @@ import path from 'path';
 import process2 from 'process';
 import { pathToFileURL } from 'url';
 import { app, protocol, ipcMain, shell, session, net } from 'electron';
-import z2 from 'zod';
+import z, { boolean } from 'zod';
 
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -2236,7 +2236,6 @@ var defaultMainPluginOptions = {
   isOAuth: true,
   BETTER_AUTH_BASEURL: "http://localhost:3002",
   ELECTRON_APP_NAME: "bigio-electron-demo",
-  PROVIDERS: ["github", "google"],
   ELECTRON_APP_HOST: "app-renderer",
   ELECTRON_SCHEME: "bigio",
   ELECTRON_RENDERER_PATH: "out/renderer",
@@ -2245,11 +2244,10 @@ var defaultMainPluginOptions = {
   CLEAR_COOKIES_EVENT_NAME: "clear-Cookies",
   GET_COOKIES_EVENT_NAME: "get-Cookies",
   ELECTRON_VERIFIER_LENGTH: 32,
-  FRONTEND_URL: "http://localhost:3002/oauth",
+  FRONTEND_URL: "http://localhost:3001/oauth",
   WEB_OAUTH_SIGNIN_CALLBACK_PATHNAME: "electron-handoff",
   SCHEME_NAME_IN_URL: "scheme",
-  PROVIDER_NAME_IN_URL: "provider",
-  CHALLENGE_NAME_IN_URL: "electron_challenge",
+  CHALLENGE_NAME_IN_URL: "electron-challenge",
   CALLBACK_PATHNAME_IN_URL: "callbackpath",
   OLD_SCHOOL_ONBEFORE_WAY: false,
   ELECTRON_CALLBACK_HOST_PATH: "better-auth-callback",
@@ -2669,6 +2667,7 @@ function safeTry(func, errorMessage) {
 var crypto = globalThis.crypto;
 var ALGO_SHA = "SHA-256";
 var GLOBAL_ENCODER = new TextEncoder();
+new TextDecoder();
 function encode64(buffer) {
   const checkBuffer = okOr(buffer, {
     msg: "Invalid buffer input for toBase64Url",
@@ -2715,11 +2714,17 @@ async function pkceGenerateChallenge(verifier) {
   });
   return encode64(hashBuffer);
 }
+z.object({
+  scopes: z.array(z.string()).optional(),
+  loginHint: z.string().optional(),
+  additionalData: z.record(z.string(), z.any()).optional(),
+  requestSignUp: boolean().optional()
+});
 
 // src/main/electron-main-plugin.ts
 import_main.default.initialize();
 var isInitializedAtom = atom(false);
-var deepLinkUrlAtom = atom(null);
+var deepLinkUrlTempAtom = atom(null);
 var browserWindowAtom = atom(null);
 var getMainWindow = () => {
   const mainWindow = browserWindowAtom.get();
@@ -2757,9 +2762,9 @@ var popUpWindow = (win) => {
   }
   win.focus();
 };
-var verifierZod = z2.object({
-  verifier: z2.string(),
-  expiresAt: z2.number()
+var verifierZod = z.object({
+  verifier: z.string(),
+  expiresAt: z.number()
 });
 var mainInjection = (options) => {
   if (isInitializedAtom.get()) {
@@ -2786,11 +2791,9 @@ var mainInjection = (options) => {
     FRONTEND_URL,
     CHALLENGE_NAME_IN_URL,
     SCHEME_NAME_IN_URL,
-    PROVIDER_NAME_IN_URL,
     ELECTRON_APP_HOST,
     ELECTRON_RENDERER_PATH,
     ELECTRON_VERIFIER_FILE_NAME,
-    PROVIDERS,
     ELECTRON_APP_NAME,
     OLD_SCHOOL_ONBEFORE_WAY,
     CONTENT_SECURITY_POLICY
@@ -2894,9 +2897,9 @@ var mainInjection = (options) => {
         deepLinkURL,
         verifier: getElectronVerifier()
       });
-      deepLinkUrlAtom.set(null);
+      deepLinkUrlTempAtom.set(null);
     } else {
-      deepLinkUrlAtom.set(deepLinkURL);
+      deepLinkUrlTempAtom.set(deepLinkURL);
     }
   };
   app.on("open-url", (event, deepLinkURL) => {
@@ -2910,7 +2913,7 @@ var mainInjection = (options) => {
   if (process2.platform === "win32") {
     const coldStartUrl = process2.argv.find((arg) => arg.startsWith(`${ELECTRON_SCHEME}://`));
     if (coldStartUrl) {
-      deepLinkUrlAtom.set(coldStartUrl);
+      deepLinkUrlTempAtom.set(coldStartUrl);
     }
   }
   app.on("second-instance", (_event, commandLine, workingDirectory) => {
@@ -2921,13 +2924,13 @@ var mainInjection = (options) => {
   });
   ipcMain.removeAllListeners(APP_MOUNTED_EVENT_NAME);
   ipcMain.on(APP_MOUNTED_EVENT_NAME, (event) => {
-    const deepLinkURL = deepLinkUrlAtom.get();
+    const deepLinkURL = deepLinkUrlTempAtom.get();
     if (deepLinkURL) {
       event.sender.send(DEEPLINK_EVENT_NAME, {
         deepLinkURL,
         verifier: getElectronVerifier()
       });
-      deepLinkUrlAtom.set(null);
+      deepLinkUrlTempAtom.set(null);
     }
   });
   ipcMain.removeHandler(GET_COOKIES_EVENT_NAME);
@@ -2977,25 +2980,6 @@ var mainInjection = (options) => {
               true
             );
             const url = new URL(targetUrl);
-            const provider = okOr(
-              url.searchParams.get(PROVIDER_NAME_IN_URL),
-              new BigIOError("No provider", {
-                bigioErrorStack: [
-                  {
-                    ctx: targetUrl
-                  }
-                ]
-              })
-            );
-            if (!PROVIDERS.includes(provider)) {
-              throw new BigIOError("Error Provider", {
-                bigioErrorStack: [
-                  {
-                    ctx: targetUrl
-                  }
-                ]
-              });
-            }
             url.searchParams.set(CHALLENGE_NAME_IN_URL, challenge);
             url.searchParams.set(SCHEME_NAME_IN_URL, ELECTRON_SCHEME);
             shell.openExternal(url.toString());