@bigio/better-auth-electron 1.0.2 → 1.0.4

package/README.md

@@ -1,40 +1,34 @@
 ## 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.
+**~~1. Architecture: The "Silent Handoff" (Stateless & Secure)~~**
 
+- [done] ~~**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.
+- ~~**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`.
+- [ ] **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.
 
+- [done] ~~**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.
+- [ ] **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
 
@@ -77,6 +71,14 @@ pnpm add better-auth electron react react-dom
 
 Initialize Better Auth with the `electronServerPlugin`. This handles the ticket exchange and verification logic on your backend.
 
+#### The "Silent Handoff" Mechanism (Stateless & Secure)
+
+This plugin implements a **Server-Side Cookie Interception** strategy to ensure strict isolation between the Web Session and the Electron Session.
+
+- It intercepts OAuth callback responses specifically for Electron. It actively **removes the `Set-Cookie` header** (which contains the session token) before the response reaches the browser.
+- This guarantees that the Electron login flow **does not overwrite or interfere** with the user's existing browser session.
+- Authentication relies solely on a one-time encrypted Ticket. The browser acts as a purely **`stateless`** transport layer for Electron.
+
 ```typescript
 import { betterAuth } from 'better-auth'
 import { electronServerPlugin } from '@bigio/better-auth-electron/server'
@@ -102,6 +104,28 @@ export const auth = betterAuth({
 
 Use `mainInjection` to setup IPC handlers and deep linking strategies. This automatically handles the "protocol" opening events.
 
+### Security & CSP Configuration
+
+** IMPORTANT: Clean up your `index.html`**
+
+This plugin automatically injects a rigorous, production-ready **Content Security Policy (CSP)** via the Main Process.
+
+**You CAN remove** any manual CSP `<meta>` tags from your `index.html` (renderer). Leaving them in will cause the browser to enforce the "intersection" of both policies, likely breaking your Auth flow (e.g., blocking the OAuth popup or API connection).
+
+**DELETE this from your `index.html`:**
+
+```html
+<meta
+  http-equiv="Content-Security-Policy"
+  content="
+  default-src 'self'; 
+  script-src 'self'; 
+  style-src 'self' 'unsafe-inline';
+  img-src 'self' data:;
+  connect-src 'self' http://localhost;
+  " />
+```
+
 ```typescript
 import { app, BrowserWindow } from 'electron'
 import { mainInjection } from '@bigio/better-auth-electron/main'
@@ -114,8 +138,13 @@ 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 if true
-  OLD_SCHOOL_ONBEFORE_WAY: false,
+  /**
+   * [Optional] Content Security Policy (CSP) Configuration
+   * * Strategy: "All-or-Nothing"
+   * - undefined (Default): The plugin automatically injects a secure, production-ready CSP (The "MVP" Fallback).
+   * - string: The plugin uses YOUR string exactly. No merging, no magic. You take full control.
+   */
+  CONTENT_SECURITY_POLICY: "default-src 'self'; ...", // override completely
 })
 
 function createWindow(): void {
@@ -134,6 +163,21 @@ app.whenReady().then(() => {
 })
 ```
 
+**If CONTENT_SECURITY_POLICY is not provided, the plugin applies the following strictly secure rules to the Main Frame (index.html) automatically. This ensures Auth works out-of-the-box while keeping your app secure.**
+
+```http
+default-src 'self';
+script-src 'self';
+style-src 'self' 'unsafe-inline';
+# Allows loading images from 'self', OAuth providers (https:), and your Auth Server
+img-src 'self' data: blob: https: ${BETTER_AUTH_BASEURL};
+# Strictly restricts API connections to 'self' and your Auth Server
+connect-src 'self' ${BETTER_AUTH_BASEURL};
+font-src 'self' data:;
+# Prevents clickjacking attacks
+frame-ancestors 'none';
+```
+
 ### 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.
@@ -158,7 +202,31 @@ export const authClient = createAuthClient({
 setLazyClient(authClient)
 ```
 
-### 4. Electron Renderer / Login Page (`src/renderer/pages/login.tsx`)
+### 4. 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
+    }),
+  ],
+})
+```
+
+### 5. 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.
 
@@ -188,56 +256,65 @@ const ElectronLoginButton = ({ provider }: { provider: string }) => {
 }
 ```
 
-### 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.
+### 6. Web/App Component Usage (`src/web/components/user-session.tsx`)
 
-```typescript
-import { createAuthClient } from 'better-auth/react'
-import { electronRendererPlugin } from '@bigio/better-auth-electron/renderer'
+The `useElectronOAuthSession` hook is the core of the "Handoff" experience. It manages the synchronization between the web authentication state and the Electron application.
 
-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
-    }),
-  ],
-})
-```
+#### Component Implementation
 
-### 6. Web/App Component Usage (`src/web/components/user-session.tsx`)
+The hook provides reactive states to manage the UI. Most importantly, the 'pending' state serves as a "Session Detected" signal.
 
-The `useElectronOAuthSession` hook is the heart of the "Handoff" experience. It listens for the deep link callback and automatically verifies the session.
+To resolve this state, you use the `setFastLogin` function. Calling this function immediately updates the oauthStatus and triggers the next step in the authentication flow.
 
-```typescript
+```tsx
+import { useEffect } from 'react'
 import { authClient } from '@/web/client'
 
 export function UserSessionStatus() {
   const {
-    data: useSessionData,
+    data: sessionData,
     error,
-    isPending,
-    isRefetching,
-    refetch,
-    // // The current status of the handoff process on the client side
-    // (e.g., 'idle' | 'succeed' | 'failed')
-    oauthMessage
+    isPending, // Initial loading state
+
+    // Status enum: 'idle' | 'pending' | 'connecting' | 'succeed' | 'failed'
+    // 'pending': CRITICAL state. It confirms a valid session ALREADY exists
+    // and the system is pausing to wait for the user's decision.
+    oauthStatus,
+    oauthError,
+
+    // Action to control the flow:
+    // setFastLogin(true)  = Fast Login (Use current session)
+    // setFastLogin(false) = Switch Account (Ignore current session)
+    setFastLogin,
   } = authClient.bigio.useElectronOAuthSession()
 
-  if (isPending) return <div>Loading session... {oauthMessage}</div>
-  if (error) return <div>Error: {error.message}</div>
-
+  /**
+   * Optional: Force Logic (Auto-decision)
+   * If you want to skip the user choice UI:
+   */
+  useEffect(() => {
+    setFastLogin(true) // Force Fast Login immediately
+    // OR
+    setFastLogin(false) // Force Switch Account immediately
+  }, [])
+
+  /**
+   * Optional: User-decision
+   * If you want to let the user choice:
+   */
   return (
     <div>
-      <h1>Welcome, {useSessionData?.user.name}</h1>
-      <p>Status: {oauthMessage || 'Idle'}</p>
+      {/* The 'pending' status indicates a session collision/detection.
+        We present the choice to the user here.
+      */}
+      {oauthStatus === 'pending' ? (
+        <>
+          {/* Option: Ignore current session and re-login */}
+          <button onClick={() => setFastLogin(false)}>Switch Account</button>
+          {/* Option: Use current session for Electron */}
+          <button onClick={() => setFastLogin(true)}>Fast Login</button>
+        </>
+      ) : null}
     </div>
   )
 }