@bigio/better-auth-electron 1.0.0 → 1.0.2

package/README.md

@@ -1,17 +1,63 @@
+## 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.
+
+Based on my study of the official implementation code, I have decided on the following to-do list:
+**1. Architecture: The "Silent Handoff" (Stateless & Secure)**
+
+* [ ] **Server-Side Cookie Interception**: Modify `electron-server-plugin` to intercept the OAuth callback response.
+* *Action*: Strip the `Set-Cookie` header (specifically the session token) from the response to prevent overwriting the user's browser session.
+* *Goal*: Achieve strict physical isolation between Web Session and Electron Session.
+
+
+* [ ] **Stateless OAuth Flow**: Ensure the OAuth flow relies solely on the encrypted `Ticket` mechanism, making the browser a purely stateless transport layer for Electron authentication.
+
+**2. Security & Hardening**
+
+* [ ] **Secure Persistence**: Implement `safeStorage` (DPAPI/Keychain) for encrypting the persisted PKCE Verifier on disk.
+* *Reason*: Prevent plaintext credentials from resting on the file system.
+
+
+* [ ] **User-Agent Scrubbing**: Global removal of "Electron" tokens from the `User-Agent` string at the `app.on('ready')` stage.
+* *Reason*: Bypass WAF/Anti-Bot protections that block Electron-based requests during the ticket exchange phase.
+
+
+* [ ] **Automated CSP Injection**: Implement `onHeadersReceived` interceptor in the Main Process.
+* *Action*: Automatically append the backend API URL to the `connect-src` directive.
+* *Goal*: Provide a "Zero-Config" experience by preventing CSP violations without requiring users to manually edit `index.html`.
+
+
+
+**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.
+
+
+* [ ] **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-based Better Auth integration for Electron.**
+**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
 
-- ** 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.
+- ** 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
 
@@ -68,8 +114,8 @@ const { windowInjection, whenReadyInjection } = mainInjection({
   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,
+  // Use the classic 'onBeforeRequest' filter approach for auth code capture if true
+  OLD_SCHOOL_ONBEFORE_WAY: false,
 })
 
 function createWindow(): void {
@@ -77,12 +123,12 @@ function createWindow(): void {
     /* config */
   })
 
-  // Inject IPC handlers into the specific window instance
+  // Inject ipcRenderer event into the specific window instance
   windowInjection(mainWindow)
 }
 
 app.whenReady().then(() => {
-  // Register custom protocol schemes and deep link listeners
+  // Register custom protocol schemes
   whenReadyInjection()
   createWindow()
 })
@@ -142,7 +188,31 @@ const ElectronLoginButton = ({ provider }: { provider: string }) => {
 }
 ```
 
-### 5. Web/App Component Usage (`src/web/components/user-session.tsx`)
+### 5. Electron Renderer/Web Client (`src/renderer/lib/auth-client.ts`)
+
+This is the auth client running **inside your Electron app**. It listens for the custom protocol deep link to hydrate the session.
+
+> **Suggestion:** set `credentials: 'include'` to ensure the session cookie generated by the secure protocol is correctly persisted.
+
+```typescript
+import { createAuthClient } from 'better-auth/react'
+import { electronRendererPlugin } from '@bigio/better-auth-electron/renderer'
+
+export const authClient = createAuthClient({
+  baseURL: 'http://localhost:3002',
+  fetchOptions: {
+    // It ensures cookies are sent/received correctly in the custom scheme.
+    credentials: 'include',
+  },
+  plugins: [
+    electronRendererPlugin({
+      ELECTRON_SCHEME: 'bigio', // Must match Main process config
+    }),
+  ],
+})
+```
+
+### 6. 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.
 
@@ -151,23 +221,13 @@ 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")
+    // // The current status of the handoff process on the client side
+    // (e.g., 'idle' | 'succeed' | 'failed')
     oauthMessage
   } = authClient.bigio.useElectronOAuthSession()