@bigio/better-auth-electron 1.0.3 → 1.0.4

package/README.md

@@ -2,13 +2,13 @@
 
 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)**
+**~~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.
+- [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**
 
@@ -28,7 +28,7 @@ Based on my study of the official implementation code, I have decided on the fol
 - _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.
+- [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
 
@@ -71,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'
@@ -130,7 +138,6 @@ const { windowInjection, whenReadyInjection } = mainInjection({
   PROVIDERS: ['github', 'google'],
   BETTER_AUTH_BASEURL: 'http://localhost:3002',
   FRONTEND_URL: 'http://localhost:3001/oauth',
-  CONTENT_SECURITY_POLICY: '',
   /**
    * [Optional] Content Security Policy (CSP) Configuration
    * * Strategy: "All-or-Nothing"
@@ -195,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.
 
@@ -225,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>
   )
 }

package/dist/main.js

@@ -3047,7 +3047,6 @@ var mainInjection = (options) => {
           const responseHeaders = {
             ...details.responseHeaders,
             "Content-Security-Policy": [CONTENT_SECURITY_POLICY ?? fallbackCSP]
-            // 注入！
           };
           callback({
             responseHeaders,