feat: anonymous BYOK with optional sign-in

Paste your own provider key and use Quorum with no sign-in - the key travels in the POST body and short-circuits before any auth import, DB read, or 402. Keyless requests still return 402 no_key on chat, consensus, and OCR. NEXT_PUBLIC_AUTH_ENABLED gates the sign-in UI and the server-side session lookup, so a zero-backend clone runs as pure BYOK. Keys live only in the browser, never stored or logged server-side. README rewritten BYOK-first.

Author: aiedwardyi

.env.example

@@ -24,6 +24,10 @@ KEY_ENCRYPTION_SECRET=generate_with_openssl_rand_-base64_32
 # Optional Gemini API key path (Google AI Studio)
 GEMINI_API_KEY=your_gemini_api_key
 
-# Public deployments: set to true so visitors must use saved BYOK keys.
+# Public deployments: set to true so visitors must supply their own key (pasted BYOK or saved).
 # Leave unset or false for local dev with server-side .env keys.
 REQUIRE_USER_API_KEYS=false
+
+# Accounts: enable the sign-in UI and the server-side session key lookup.
+# Build-time inlined (NEXT_PUBLIC_) - rebuild after changing. Leave false for pure BYOK, no accounts.
+NEXT_PUBLIC_AUTH_ENABLED=false

README.md

@@ -83,36 +83,38 @@ Switch instantly from the header or settings.
 
 ## Quick Start
 
+Quorum is **BYOK-first (bring your own key)**: paste your own provider API keys and go. No account, no database, no sign-in. Keys are stored only in your browser.
+
 ```bash
 git clone https://github.com/aiedwardyi/quorum.git
 cd quorum
 npm install
+npm run dev
 ```
 
-Create a `.env.local` file from [`.env.example`](./.env.example):
+Open [localhost:3000](http://localhost:3000), open **Settings**, and paste an API key for any provider you want on the panel. That is the whole setup.
 
-```bash
-cp .env.example .env.local
-```
+> The consensus verdict and document OCR always run on **Gemini**, so add a Gemini key even if your panel is Claude/GPT/Perplexity only.
 
-```powershell
-Copy-Item .env.example .env.local
-```
+Set `REQUIRE_USER_API_KEYS=true` (recommended for any BYOK or public deploy) so a keyless request returns a clear "add your key" prompt instead of a generic provider error. Anonymous BYOK gives you an in-session thread; sign in (below) to save history across visits.
 
-Fill in your credentials (see `.env.example` for all placeholders). Quorum is BYOK-first: you can run it with server-side provider keys in `.env.local`, and signed-in users can save their own encrypted provider keys from Settings.
+---
 
-```env
-# Gemini option A: Google AI Studio API key
-GEMINI_API_KEY=your_gemini_api_key
+## Self-Hosting with Accounts (optional)
 
-# Gemini option B: Vertex AI with Application Default Credentials
-VERTEX_PROJECT_ID=your_google_cloud_project_id
-VERTEX_LOCATION=us-central1
+Sign-in is an optional upgrade: saved, encrypted provider keys and thread history synced to a database. Skip this entire section for pure BYOK.
 
-# Model Providers
-PERPLEXITY_API_KEY=your_perplexity_api_key
-ANTHROPIC_API_KEY=your_anthropic_api_key
-OPENAI_API_KEY=your_openai_api_key
+Create a `.env.local` from [`.env.example`](./.env.example):
+
+```bash
+cp .env.example .env.local        # PowerShell: Copy-Item .env.example .env.local
+```
+
+```env
+# Enable accounts: sign-in UI + the server-side session key lookup.
+# Build-time inlined - rebuild after changing.
+NEXT_PUBLIC_AUTH_ENABLED=true
+REQUIRE_USER_API_KEYS=true
 
 # Database (Neon PostgreSQL)
 DATABASE_URL=postgresql://user:password@host/neondb?sslmode=require
@@ -122,35 +124,43 @@ AUTH_SECRET=generate_with_openssl_rand_-base64_32
 GOOGLE_CLIENT_ID=your_google_oauth_client_id
 GOOGLE_CLIENT_SECRET=your_google_oauth_client_secret
 
-# Encryption for user-supplied API keys
+# Encryption for accounts' saved provider keys
 KEY_ENCRYPTION_SECRET=generate_with_openssl_rand_-base64_32
+
+# Optional server-side provider keys (used only when REQUIRE_USER_API_KEYS is false)
+GEMINI_API_KEY=your_gemini_api_key
+PERPLEXITY_API_KEY=your_perplexity_api_key
+ANTHROPIC_API_KEY=your_anthropic_api_key
+OPENAI_API_KEY=your_openai_api_key
 ```
 
 > **Important:** Prefer `.env.local` for local secrets. It takes precedence over `.env` and is gitignored by default.
 
-Gemini supports two server-side auth paths:
-
-- Google AI Studio/API key: set `GEMINI_API_KEY`.
-- Vertex AI ADC: leave `GEMINI_API_KEY` empty, set `VERTEX_PROJECT_ID` and `VERTEX_LOCATION`, then authenticate locally:
-
-```bash
-gcloud auth application-default login
-```
-
-For local Google login, create a Google OAuth client and add this authorized redirect URI:
+For Google login, create a Google OAuth client and add this authorized redirect URI:
 
 ```text
 http://localhost:3000/api/auth/callback/google
 ```
 
-Then initialize the database and run the app:
+Gemini has two server-side auth paths (only relevant when serving your own keys):
+
+- Google AI Studio API key: set `GEMINI_API_KEY`.
+- Vertex AI ADC: leave `GEMINI_API_KEY` empty, set `VERTEX_PROJECT_ID` and `VERTEX_LOCATION`, then `gcloud auth application-default login`.
+
+Then migrate the database and run:
 
 ```bash
 npx prisma migrate dev
 npm run dev
 ```
 
-Open [localhost:3000](http://localhost:3000) and start debating.
+---
+
+## Privacy & Security
+
+- Your keys live only in your browser's `localStorage` and are sent to the server solely to call the model you picked. They are never persisted or logged server-side.
+- Signed-in users' saved keys are encrypted at rest, scoped per account, and never travel back to the client.
+- Browser BYOK is inherently exposed to XSS: any script running on the page can read `localStorage`. Use your own revocable keys, and self-hosters should serve a strict Content-Security-Policy.
 
 ---
 

scripts/write-env.js

@@ -9,6 +9,7 @@ const keys = [
   "KEY_ENCRYPTION_SECRET",
   "NEXTAUTH_URL",
   "REQUIRE_USER_API_KEYS",
+  "NEXT_PUBLIC_AUTH_ENABLED",
   "GEMINI_API_KEY",
   "VERTEX_PROJECT_ID",
   "VERTEX_LOCATION",

src/__tests__/byok-route-guards.test.ts

@@ -87,10 +87,13 @@ function jsonRequest(path: string, body: unknown): Request {
 
 describe("BYOK-required route guards", () => {
   let previousRequireUserApiKeys: string | undefined
+  let previousAuthEnabled: string | undefined
 
   beforeEach(() => {
     previousRequireUserApiKeys = process.env.REQUIRE_USER_API_KEYS
     process.env.REQUIRE_USER_API_KEYS = "true"
+    previousAuthEnabled = process.env.NEXT_PUBLIC_AUTH_ENABLED
+    process.env.NEXT_PUBLIC_AUTH_ENABLED = "true"
     authMock.mockResolvedValue(null)
     getUserProviderApiKeyMock.mockResolvedValue(undefined)
     streamGPTMock.mockImplementation(async function* () {
@@ -106,6 +109,11 @@ describe("BYOK-required route guards", () => {
     } else {
       process.env.REQUIRE_USER_API_KEYS = previousRequireUserApiKeys
     }
+    if (previousAuthEnabled === undefined) {
+      delete process.env.NEXT_PUBLIC_AUTH_ENABLED
+    } else {
+      process.env.NEXT_PUBLIC_AUTH_ENABLED = previousAuthEnabled
+    }
     vi.clearAllMocks()
   })
 
@@ -267,4 +275,179 @@ describe("BYOK-required route guards", () => {
       expect.objectContaining({ apiKey: "server-gemini-key" })
     )
   })
+
+  // ---- Anonymous body-key BYOK (Phase 1) ----
+
+  it("chat uses a request-body key without touching auth or the DB", async () => {
+    const response = await chatPOST(
+      jsonRequest("/api/chat", {
+        messages,
+        provider: "gpt",
+        locale: "en",
+        responseLength: "medium",
+        userApiKey: "body-gpt-key",
+      })
+    )
+
+    expect(response.status).toBe(200)
+    await response.text()
+    expect(streamGPTMock.mock.calls[0]?.[4]).toBe("body-gpt-key")
+    expect(authMock).not.toHaveBeenCalled()
+    expect(getUserProviderApiKeyMock).not.toHaveBeenCalled()
+  })
+
+  it("consensus uses a request-body gemini key without touching auth", async () => {
+    const response = await consensusPOST(
+      jsonRequest("/api/consensus", {
+        messages,
+        locale: "en",
+        responseLength: "medium",
+        userApiKey: "body-gemini-key",
+      }) as never
+    )
+
+    expect(response.status).toBe(200)
+    await expect(response.json()).resolves.toMatchObject(validVerdict)
+    expect(generateGeminiVerdictWithApiKeyMock).toHaveBeenCalledWith(
+      expect.objectContaining({ apiKey: "body-gemini-key" })
+    )
+    expect(authMock).not.toHaveBeenCalled()
+  })
+
+  it("ocr uses a request-body gemini key without touching auth", async () => {
+    const response = await ocrPOST(
+      jsonRequest("/api/ocr", { images: ["abc"], userApiKey: "body-gemini-key" }) as never
+    )
+
+    expect(response.status).toBe(200)
+    await expect(response.json()).resolves.toEqual({ text: "ocr text" })
+    expect(generateGoogleAiContentWithApiKeyMock).toHaveBeenCalledWith(
+      expect.objectContaining({ apiKey: "body-gemini-key" })
+    )
+    expect(authMock).not.toHaveBeenCalled()
+  })
+
+  it("chat body key takes precedence over a saved session key", async () => {
+    authMock.mockResolvedValue({ user: { id: "user-1" } })
+    getUserProviderApiKeyMock.mockResolvedValue("session-gpt-key")
+
+    const response = await chatPOST(
+      jsonRequest("/api/chat", {
+        messages,
+        provider: "gpt",
+        locale: "en",
+        responseLength: "medium",
+        userApiKey: "body-gpt-key",
+      })
+    )
+
+    expect(response.status).toBe(200)
+    await response.text()
+    expect(streamGPTMock.mock.calls[0]?.[4]).toBe("body-gpt-key")
+    expect(authMock).not.toHaveBeenCalled()
+    expect(getUserProviderApiKeyMock).not.toHaveBeenCalled()
+  })
+
+  // ---- Auth gate (Phase 2): flag off never touches the session ----
+
+  it("skips the session lookup entirely when auth is disabled, still 402 without a key", async () => {
+    process.env.NEXT_PUBLIC_AUTH_ENABLED = "false"
+    authMock.mockResolvedValue({ user: { id: "user-1" } })
+    getUserProviderApiKeyMock.mockResolvedValue("session-gpt-key")
+
+    const response = await chatPOST(
+      jsonRequest("/api/chat", {
+        messages,
+        provider: "gpt",
+        locale: "en",
+        responseLength: "medium",
+      })
+    )
+
+    expect(response.status).toBe(402)
+    await expect(response.json()).resolves.toEqual({ error: "no_key", provider: "gpt" })
+    expect(authMock).not.toHaveBeenCalled()
+    expect(streamGPTMock).not.toHaveBeenCalled()
+  })
+
+  it("does not log the request-body key when the provider errors", async () => {
+    const leakyKey = "sk-body-leak-1234567890abcdefghij"
+    streamGPTMock.mockImplementation(async function* () {
+      yield "partial"
+      throw new Error(`Provider auth failed for key ${leakyKey}`)
+    })
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
+
+    try {
+      const response = await chatPOST(
+        jsonRequest("/api/chat", {
+          messages,
+          provider: "gpt",
+          locale: "en",
+          responseLength: "medium",
+          userApiKey: leakyKey,
+        })
+      )
+      const streamed = await response.text()
+
+      expect(errorSpy).toHaveBeenCalled()
+      for (const call of errorSpy.mock.calls) {
+        expect(call.map(String).join(" ")).not.toContain(leakyKey)
+      }
+      expect(streamed).not.toContain(leakyKey)
+    } finally {
+      errorSpy.mockRestore()
+    }
+  })
+
+  it("consensus does not log the request-body key when the provider errors", async () => {
+    const leakyKey = "AIzaBodyLeakConsensus1234567890abcd"
+    generateGeminiVerdictWithApiKeyMock.mockRejectedValue(
+      new Error(`Vertex auth failed for key ${leakyKey}`)
+    )
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
+
+    try {
+      const response = await consensusPOST(
+        jsonRequest("/api/consensus", {
+          messages,
+          locale: "en",
+          responseLength: "medium",
+          userApiKey: leakyKey,
+        }) as never
+      )
+      const bodyText = await response.text()
+
+      expect(errorSpy).toHaveBeenCalled()
+      for (const call of errorSpy.mock.calls) {
+        expect(call.map(String).join(" ")).not.toContain(leakyKey)
+      }
+      expect(bodyText).not.toContain(leakyKey)
+    } finally {
+      errorSpy.mockRestore()
+    }
+  })
+
+  it("ocr does not log the request-body key when the provider errors", async () => {
+    const leakyKey = "AIzaBodyLeakOcr1234567890abcdefghij"
+    generateGoogleAiContentWithApiKeyMock.mockRejectedValue(
+      new Error(`Vertex auth failed for key ${leakyKey}`)
+    )
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
+
+    try {
+      const response = await ocrPOST(
+        jsonRequest("/api/ocr", { images: ["abc"], userApiKey: leakyKey }) as never
+      )
+      const bodyText = await response.text()
+
+      expect(errorSpy).toHaveBeenCalled()
+      for (const call of errorSpy.mock.calls) {
+        expect(call.map(String).join(" ")).not.toContain(leakyKey)
+      }
+      expect(bodyText).not.toContain(leakyKey)
+    } finally {
+      errorSpy.mockRestore()
+    }
+  })
 })