feat: require user api keys in public deploy

Require saved user provider keys in public deployments and keep local server-key fallback behind REQUIRE_USER_API_KEYS=false.

Author: aiedwardyi

.env.example

@@ -23,3 +23,7 @@ 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.
+# Leave unset or false for local dev with server-side .env keys.
+REQUIRE_USER_API_KEYS=false

scripts/write-env.js

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

src/__tests__/api-key-errors.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest"
+import {
+  getMissingApiKeyMessage,
+  parseNoKeyProvider,
+  parseNoKeyProviderFromResponse,
+} from "@/lib/api-key-errors"
+
+describe("api key error helpers", () => {
+  it("recognizes no_key responses with a known provider", () => {
+    expect(parseNoKeyProvider({ error: "no_key", provider: "gemini" })).toBe("gemini")
+    expect(parseNoKeyProvider({ error: "no_key", provider: "bogus" })).toBeNull()
+    expect(parseNoKeyProvider({ error: "other", provider: "gemini" })).toBeNull()
+  })
+
+  it("returns null for malformed no_key payloads", () => {
+    expect(parseNoKeyProvider(null)).toBeNull()
+    expect(parseNoKeyProvider(undefined)).toBeNull()
+    expect(parseNoKeyProvider("no_key")).toBeNull()
+    expect(parseNoKeyProvider({ error: "no_key" })).toBeNull()
+    expect(parseNoKeyProvider({ error: "no_key", provider: 123 })).toBeNull()
+  })
+
+  it("parses no_key provider from a response body", async () => {
+    const response = Response.json({ error: "no_key", provider: "claude" }, { status: 402 })
+
+    await expect(parseNoKeyProviderFromResponse(response)).resolves.toBe("claude")
+  })
+
+  it("returns null when response JSON parsing fails", async () => {
+    const response = new Response("{", {
+      status: 402,
+      headers: { "Content-Type": "application/json" },
+    })
+
+    await expect(parseNoKeyProviderFromResponse(response)).resolves.toBeNull()
+  })
+
+  it("formats the user-facing Settings message", () => {
+    expect(getMissingApiKeyMessage("gpt")).toBe(
+      "Add your GPT API key in Settings to start debating."
+    )
+  })
+
+  it("formats the Settings message in Korean", () => {
+    expect(getMissingApiKeyMessage("gemini", "ko")).toBe(
+      "Settings에서 Gemini API 키를 추가해 토론을 시작하세요."
+    )
+  })
+})

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

@@ -0,0 +1,270 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+import type { Message } from "@/types"
+
+const authMock = vi.hoisted(() => vi.fn())
+const getUserProviderApiKeyMock = vi.hoisted(() => vi.fn())
+const streamGPTMock = vi.hoisted(() => vi.fn())
+const generateGeminiVerdictWithApiKeyMock = vi.hoisted(() => vi.fn())
+const generateGoogleAiContentWithApiKeyMock = vi.hoisted(() => vi.fn())
+
+const validVerdict = {
+  recommendedAnswer: "Choose Option A.",
+  voteSplit: "2/2 unanimous",
+  confidence: 88,
+  reasons: ["Reason one", "Reason two"],
+  minorityView: "Option B could work with different constraints.",
+  oppositeCase: "Choose B if latency matters most.",
+}
+
+vi.mock("@/lib/auth", () => ({ auth: authMock }))
+vi.mock("@/lib/user-api-keys", () => ({ getUserProviderApiKey: getUserProviderApiKeyMock }))
+vi.mock("@/lib/providers/gpt", () => ({ streamGPT: streamGPTMock }))
+vi.mock("@/lib/providers/claude", () => ({ streamClaude: vi.fn() }))
+vi.mock("@/lib/providers/perplexity", () => ({ streamPerplexity: vi.fn() }))
+vi.mock("@/lib/providers/gemini", () => ({
+  getConfiguredGeminiApiKey: vi.fn(() => "server-gemini-key"),
+  generateGeminiVerdictWithApiKey: generateGeminiVerdictWithApiKeyMock,
+  generateGoogleAiContentWithApiKey: generateGoogleAiContentWithApiKeyMock,
+  streamGemini: vi.fn(),
+}))
+vi.mock("@/lib/vertex-config", () => ({
+  getVertexConfig: () => ({ projectId: "project", location: "us-central1" }),
+}))
+vi.mock("@google-cloud/vertexai", () => ({
+  VertexAI: vi.fn(() => ({
+    getGenerativeModel: vi.fn(() => ({
+      generateContent: vi.fn(),
+    })),
+  })),
+  HarmCategory: {
+    HARM_CATEGORY_HARASSMENT: "harassment",
+    HARM_CATEGORY_DANGEROUS_CONTENT: "dangerous",
+  },
+  HarmBlockThreshold: { BLOCK_ONLY_HIGH: "high" },
+  SchemaType: {
+    OBJECT: "object",
+    STRING: "string",
+    NUMBER: "number",
+    ARRAY: "array",
+  },
+}))
+
+import { POST as chatPOST } from "@/app/api/chat/route"
+import { POST as consensusPOST } from "@/app/api/consensus/route"
+import { POST as ocrPOST } from "@/app/api/ocr/route"
+
+const messages: Message[] = [
+  {
+    id: "u1",
+    sender: "user",
+    displayName: "You",
+    content: "Which option?",
+    timestamp: new Date(),
+  },
+  {
+    id: "g1",
+    sender: "gemini",
+    displayName: "Gemini",
+    content: "Option A.",
+    timestamp: new Date(),
+  },
+  {
+    id: "c1",
+    sender: "claude",
+    displayName: "Claude",
+    content: "Option B.",
+    timestamp: new Date(),
+  },
+]
+
+function jsonRequest(path: string, body: unknown): Request {
+  return new Request(`http://localhost${path}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  })
+}
+
+describe("BYOK-required route guards", () => {
+  let previousRequireUserApiKeys: string | undefined
+
+  beforeEach(() => {
+    previousRequireUserApiKeys = process.env.REQUIRE_USER_API_KEYS
+    process.env.REQUIRE_USER_API_KEYS = "true"
+    authMock.mockResolvedValue(null)
+    getUserProviderApiKeyMock.mockResolvedValue(undefined)
+    streamGPTMock.mockImplementation(async function* () {
+      yield "server response"
+    })
+    generateGeminiVerdictWithApiKeyMock.mockResolvedValue(JSON.stringify(validVerdict))
+    generateGoogleAiContentWithApiKeyMock.mockResolvedValue("ocr text")
+  })
+
+  afterEach(() => {
+    if (previousRequireUserApiKeys === undefined) {
+      delete process.env.REQUIRE_USER_API_KEYS
+    } else {
+      process.env.REQUIRE_USER_API_KEYS = previousRequireUserApiKeys
+    }
+    vi.clearAllMocks()
+  })
+
+  it("chat returns no_key before calling the provider when no user key exists", async () => {
+    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(streamGPTMock).not.toHaveBeenCalled()
+  })
+
+  it("chat returns key_lookup_failed when the saved key lookup fails", async () => {
+    authMock.mockResolvedValue({ user: { id: "user-1" } })
+    getUserProviderApiKeyMock.mockRejectedValueOnce(new Error("database unavailable"))
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
+
+    try {
+      const response = await chatPOST(
+        jsonRequest("/api/chat", {
+          messages,
+          provider: "gpt",
+          locale: "en",
+          responseLength: "medium",
+        })
+      )
+
+      expect(response.status).toBe(500)
+      await expect(response.json()).resolves.toEqual({ error: "key_lookup_failed" })
+      expect(streamGPTMock).not.toHaveBeenCalled()
+    } finally {
+      errorSpy.mockRestore()
+    }
+  })
+
+  it("consensus returns no_key before using Gemini server credentials", async () => {
+    const response = await consensusPOST(
+      jsonRequest("/api/consensus", {
+        messages,
+        locale: "en",
+        responseLength: "medium",
+      }) as never
+    )
+
+    expect(response.status).toBe(402)
+    await expect(response.json()).resolves.toEqual({ error: "no_key", provider: "gemini" })
+    expect(generateGeminiVerdictWithApiKeyMock).not.toHaveBeenCalled()
+  })
+
+  it("ocr returns no_key before using Gemini server credentials", async () => {
+    const response = await ocrPOST(jsonRequest("/api/ocr", { images: ["abc"] }) as never)
+
+    expect(response.status).toBe(402)
+    await expect(response.json()).resolves.toEqual({ error: "no_key", provider: "gemini" })
+    expect(generateGoogleAiContentWithApiKeyMock).not.toHaveBeenCalled()
+  })
+
+  it("chat proceeds with the saved user key when BYOK is required", async () => {
+    authMock.mockResolvedValue({ user: { id: "user-1" } })
+    getUserProviderApiKeyMock.mockResolvedValue("user-gpt-key")
+
+    const response = await chatPOST(
+      jsonRequest("/api/chat", {
+        messages,
+        provider: "gpt",
+        locale: "en",
+        responseLength: "medium",
+      })
+    )
+
+    expect(response.status).toBe(200)
+    await response.text()
+    expect(streamGPTMock).toHaveBeenCalled()
+    expect(streamGPTMock.mock.calls[0]?.[4]).toBe("user-gpt-key")
+  })
+
+  it("chat proceeds without a user key when BYOK is disabled", async () => {
+    process.env.REQUIRE_USER_API_KEYS = "false"
+
+    const response = await chatPOST(
+      jsonRequest("/api/chat", {
+        messages,
+        provider: "gpt",
+        locale: "en",
+        responseLength: "medium",
+      })
+    )
+
+    expect(response.status).toBe(200)
+    await response.text()
+    expect(streamGPTMock).toHaveBeenCalled()
+    expect(streamGPTMock.mock.calls[0]?.[4]).toBeUndefined()
+  })
+
+  it("consensus proceeds with the saved Gemini key when BYOK is required", async () => {
+    authMock.mockResolvedValue({ user: { id: "user-1" } })
+    getUserProviderApiKeyMock.mockResolvedValue("user-gemini-key")
+
+    const response = await consensusPOST(
+      jsonRequest("/api/consensus", {
+        messages,
+        locale: "en",
+        responseLength: "medium",
+      }) as never
+    )
+
+    expect(response.status).toBe(200)
+    await expect(response.json()).resolves.toMatchObject(validVerdict)
+    expect(generateGeminiVerdictWithApiKeyMock).toHaveBeenCalledWith(
+      expect.objectContaining({ apiKey: "user-gemini-key" })
+    )
+  })
+
+  it("consensus falls back to the configured Gemini key when BYOK is unset", async () => {
+    delete process.env.REQUIRE_USER_API_KEYS
+
+    const response = await consensusPOST(
+      jsonRequest("/api/consensus", {
+        messages,
+        locale: "en",
+        responseLength: "medium",
+      }) as never
+    )
+
+    expect(response.status).toBe(200)
+    await expect(response.json()).resolves.toMatchObject(validVerdict)
+    expect(generateGeminiVerdictWithApiKeyMock).toHaveBeenCalledWith(
+      expect.objectContaining({ apiKey: "server-gemini-key" })
+    )
+  })
+
+  it("ocr proceeds with the saved Gemini key when BYOK is required", async () => {
+    authMock.mockResolvedValue({ user: { id: "user-1" } })
+    getUserProviderApiKeyMock.mockResolvedValue("user-gemini-key")
+
+    const response = await ocrPOST(jsonRequest("/api/ocr", { images: ["abc"] }) as never)
+
+    expect(response.status).toBe(200)
+    await expect(response.json()).resolves.toEqual({ text: "ocr text" })
+    expect(generateGoogleAiContentWithApiKeyMock).toHaveBeenCalledWith(
+      expect.objectContaining({ apiKey: "user-gemini-key" })
+    )
+  })
+
+  it("ocr falls back to the configured Gemini key when BYOK is disabled", async () => {
+    process.env.REQUIRE_USER_API_KEYS = "false"
+
+    const response = await ocrPOST(jsonRequest("/api/ocr", { images: ["abc"] }) as never)
+
+    expect(response.status).toBe(200)
+    await expect(response.json()).resolves.toEqual({ text: "ocr text" })
+    expect(generateGoogleAiContentWithApiKeyMock).toHaveBeenCalledWith(
+      expect.objectContaining({ apiKey: "server-gemini-key" })
+    )
+  })
+})

src/__tests__/deploy-config.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from "vitest"
+import { requireUserKeys } from "@/lib/deploy-config"
+
+describe("requireUserKeys", () => {
+  it("is enabled only when REQUIRE_USER_API_KEYS is exactly true", () => {
+    const previous = process.env.REQUIRE_USER_API_KEYS
+    try {
+      process.env.REQUIRE_USER_API_KEYS = "true"
+      expect(requireUserKeys()).toBe(true)
+
+      process.env.REQUIRE_USER_API_KEYS = "TRUE"
+      expect(requireUserKeys()).toBe(false)
+
+      delete process.env.REQUIRE_USER_API_KEYS
+      expect(requireUserKeys()).toBe(false)
+    } finally {
+      if (previous === undefined) {
+        delete process.env.REQUIRE_USER_API_KEYS
+      } else {
+        process.env.REQUIRE_USER_API_KEYS = previous
+      }
+    }
+  })
+})

src/__tests__/write-env.test.ts

@@ -0,0 +1,26 @@
+import { execFileSync } from "node:child_process"
+import { mkdtempSync, readFileSync, rmSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { describe, expect, it } from "vitest"
+
+describe("write-env", () => {
+  it("writes REQUIRE_USER_API_KEYS when present in the build environment", () => {
+    const tempDir = mkdtempSync(join(tmpdir(), "quorum-write-env-"))
+    const scriptPath = join(process.cwd(), "scripts", "write-env.js")
+
+    try {
+      execFileSync(process.execPath, [scriptPath], {
+        cwd: tempDir,
+        env: {
+          ...process.env,
+          REQUIRE_USER_API_KEYS: "true",
+        },
+      })
+
+      expect(readFileSync(join(tempDir, ".env"), "utf8")).toContain("REQUIRE_USER_API_KEYS='true'")
+    } finally {
+      rmSync(tempDir, { recursive: true, force: true })
+    }
+  })
+})