fix: add API key validation for non-ASCII characters in OpenAI-compatible providers

roomote · daniel-lxs · commit ce0fc7a7178d · 2025-09-04T00:25:29.000-05:00
- Created shared validation utility to check for non-ASCII characters in API keys - Added validation to all OpenAI-compatible providers to prevent ByteString conversion errors - Provides clear error messages when invalid characters are detected - Fixes issue #7483 where non-ASCII characters in API keys caused cryptic errors
diff --git a/src/api/providers/base-openai-compatible-provider.ts b/src/api/providers/base-openai-compatible-provider.ts
@@ -10,6 +10,7 @@ import { convertToOpenAiMessages } from "../transform/openai-format"
 import type { SingleCompletionHandler, ApiHandlerCreateMessageMetadata } from "../index"
 import { DEFAULT_HEADERS } from "./constants"
 import { BaseProvider } from "./base-provider"
+import { validateApiKeyForByteString } from "./utils/api-key-validation"
 
 type BaseOpenAiCompatibleProviderOptions<ModelName extends string> = ApiHandlerOptions & {
 	providerName: string
@@ -55,6 +56,9 @@ export abstract class BaseOpenAiCompatibleProvider<ModelName extends string>
 			throw new Error("API key is required")
 		}
 
+		// Validate API key for ByteString compatibility
+		validateApiKeyForByteString(this.options.apiKey, this.providerName)
+
 		this.client = new OpenAI({
 			baseURL,
 			apiKey: this.options.apiKey,
diff --git a/src/api/providers/huggingface.ts b/src/api/providers/huggingface.ts
@@ -8,6 +8,7 @@ import type { SingleCompletionHandler, ApiHandlerCreateMessageMetadata } from ".
 import { DEFAULT_HEADERS } from "./constants"
 import { BaseProvider } from "./base-provider"
 import { getHuggingFaceModels, getCachedHuggingFaceModels } from "./fetchers/huggingface"
+import { validateApiKeyForByteString } from "./utils/api-key-validation"
 
 export class HuggingFaceHandler extends BaseProvider implements SingleCompletionHandler {
 	private client: OpenAI
@@ -22,6 +23,9 @@ export class HuggingFaceHandler extends BaseProvider implements SingleCompletion
 			throw new Error("Hugging Face API key is required")
 		}
 
+		// Validate API key for ByteString compatibility
+		validateApiKeyForByteString(this.options.huggingFaceApiKey, "HuggingFace")
+
 		this.client = new OpenAI({
 			baseURL: "https://router.huggingface.co/v1",
 			apiKey: this.options.huggingFaceApiKey,
diff --git a/src/api/providers/lm-studio.ts b/src/api/providers/lm-studio.ts
@@ -15,6 +15,7 @@ import { BaseProvider } from "./base-provider"
 import type { SingleCompletionHandler, ApiHandlerCreateMessageMetadata } from "../index"
 import { getModels, getModelsFromCache } from "./fetchers/modelCache"
 import { getApiRequestTimeout } from "./utils/timeout-config"
+import { validateApiKeyForByteString } from "./utils/api-key-validation"
 
 export class LmStudioHandler extends BaseProvider implements SingleCompletionHandler {
 	protected options: ApiHandlerOptions
@@ -24,9 +25,13 @@ export class LmStudioHandler extends BaseProvider implements SingleCompletionHan
 		super()
 		this.options = options
 
+		// LM Studio uses "noop" as a placeholder API key, but we should still validate if a real key is provided
+		const apiKey = "noop"
+		validateApiKeyForByteString(apiKey, "LM Studio")
+
 		this.client = new OpenAI({
 			baseURL: (this.options.lmStudioBaseUrl || "http://localhost:1234") + "/v1",
-			apiKey: "noop",
+			apiKey: apiKey,
 			timeout: getApiRequestTimeout(),
 		})
 	}
diff --git a/src/api/providers/ollama.ts b/src/api/providers/ollama.ts
@@ -14,6 +14,7 @@ import { ApiStream } from "../transform/stream"
 import { BaseProvider } from "./base-provider"
 import type { SingleCompletionHandler, ApiHandlerCreateMessageMetadata } from "../index"
 import { getApiRequestTimeout } from "./utils/timeout-config"
+import { validateApiKeyForByteString } from "./utils/api-key-validation"
 
 type CompletionUsage = OpenAI.Chat.Completions.ChatCompletionChunk["usage"]
 
@@ -29,6 +30,9 @@ export class OllamaHandler extends BaseProvider implements SingleCompletionHandl
 		// Otherwise use "ollama" as a placeholder for local instances
 		const apiKey = this.options.ollamaApiKey || "ollama"
 
+		// Validate API key for ByteString compatibility
+		validateApiKeyForByteString(apiKey, "Ollama")
+
 		const headers: Record<string, string> = {}
 		if (this.options.ollamaApiKey) {
 			headers["Authorization"] = `Bearer ${this.options.ollamaApiKey}`
diff --git a/src/api/providers/openai-native.ts b/src/api/providers/openai-native.ts
@@ -22,6 +22,7 @@ import { getModelParams } from "../transform/model-params"
 
 import { BaseProvider } from "./base-provider"
 import type { SingleCompletionHandler, ApiHandlerCreateMessageMetadata } from "../index"
+import { validateApiKeyForByteString } from "./utils/api-key-validation"
 
 export type OpenAiNativeModel = ReturnType<OpenAiNativeHandler["getModel"]>
 
@@ -59,6 +60,10 @@ export class OpenAiNativeHandler extends BaseProvider implements SingleCompletio
 			this.options.enableGpt5ReasoningSummary = true
 		}
 		const apiKey = this.options.openAiNativeApiKey ?? "not-provided"
+
+		// Validate API key for ByteString compatibility
+		validateApiKeyForByteString(apiKey, "OpenAI Native")
+
 		this.client = new OpenAI({ baseURL: this.options.openAiNativeBaseUrl, apiKey })
 	}
 
diff --git a/src/api/providers/openai.ts b/src/api/providers/openai.ts
@@ -24,6 +24,7 @@ import { DEFAULT_HEADERS } from "./constants"
 import { BaseProvider } from "./base-provider"
 import type { SingleCompletionHandler, ApiHandlerCreateMessageMetadata } from "../index"
 import { getApiRequestTimeout } from "./utils/timeout-config"
+import { validateApiKeyForByteString } from "./utils/api-key-validation"
 
 // TODO: Rename this to OpenAICompatibleHandler. Also, I think the
 // `OpenAINativeHandler` can subclass from this, since it's obviously
@@ -42,6 +43,9 @@ export class OpenAiHandler extends BaseProvider implements SingleCompletionHandl
 		const urlHost = this._getUrlHost(this.options.openAiBaseUrl)
 		const isAzureOpenAi = urlHost === "azure.com" || urlHost.endsWith(".azure.com") || options.openAiUseAzure
 
+		// Validate API key for ByteString compatibility
+		validateApiKeyForByteString(apiKey, "OpenAI")
+
 		const headers = {
 			...DEFAULT_HEADERS,
 			...(this.options.openAiHeaders || {}),
diff --git a/src/api/providers/openrouter.ts b/src/api/providers/openrouter.ts
@@ -25,6 +25,7 @@ import { getModelEndpoints } from "./fetchers/modelEndpointCache"
 import { DEFAULT_HEADERS } from "./constants"
 import { BaseProvider } from "./base-provider"
 import type { SingleCompletionHandler } from "../index"
+import { validateApiKeyForByteString } from "./utils/api-key-validation"
 
 // Image generation types
 interface ImageGenerationResponse {
@@ -93,6 +94,9 @@ export class OpenRouterHandler extends BaseProvider implements SingleCompletionH
 		const baseURL = this.options.openRouterBaseUrl || "https://openrouter.ai/api/v1"
 		const apiKey = this.options.openRouterApiKey ?? "not-provided"
 
+		// Validate API key for ByteString compatibility
+		validateApiKeyForByteString(apiKey, "OpenRouter")
+
 		this.client = new OpenAI({ baseURL, apiKey, defaultHeaders: DEFAULT_HEADERS })
 	}
 
diff --git a/src/api/providers/requesty.ts b/src/api/providers/requesty.ts
@@ -16,6 +16,7 @@ import { getModels } from "./fetchers/modelCache"
 import { BaseProvider } from "./base-provider"
 import type { SingleCompletionHandler, ApiHandlerCreateMessageMetadata } from "../index"
 import { toRequestyServiceUrl } from "../../shared/utils/requesty"
+import { validateApiKeyForByteString } from "./utils/api-key-validation"
 
 // Requesty usage includes an extra field for Anthropic use cases.
 // Safely cast the prompt token details section to the appropriate structure.
@@ -49,9 +50,14 @@ export class RequestyHandler extends BaseProvider implements SingleCompletionHan
 		this.options = options
 		this.baseURL = toRequestyServiceUrl(options.requestyBaseUrl)
 
+		const apiKey = this.options.requestyApiKey ?? "not-provided"
+
+		// Validate API key for ByteString compatibility
+		validateApiKeyForByteString(apiKey, "Requesty")
+
 		this.client = new OpenAI({
 			baseURL: this.baseURL,
-			apiKey: this.options.requestyApiKey ?? "not-provided",
+			apiKey: apiKey,
 			defaultHeaders: DEFAULT_HEADERS,
 		})
 	}
diff --git a/src/api/providers/router-provider.ts b/src/api/providers/router-provider.ts
@@ -8,6 +8,7 @@ import { BaseProvider } from "./base-provider"
 import { getModels } from "./fetchers/modelCache"
 
 import { DEFAULT_HEADERS } from "./constants"
+import { validateApiKeyForByteString } from "./utils/api-key-validation"
 
 type RouterProviderOptions = {
 	name: RouterName
@@ -45,6 +46,9 @@ export abstract class RouterProvider extends BaseProvider {
 		this.defaultModelId = defaultModelId
 		this.defaultModelInfo = defaultModelInfo
 
+		// Validate API key for ByteString compatibility
+		validateApiKeyForByteString(apiKey, name)
+
 		this.client = new OpenAI({
 			baseURL,
 			apiKey,
diff --git a/src/api/providers/utils/__tests__/api-key-validation.spec.ts b/src/api/providers/utils/__tests__/api-key-validation.spec.ts
@@ -0,0 +1,93 @@
+import { describe, it, expect } from "vitest"
+import { validateApiKeyForByteString, validateApiKeyForAscii } from "../api-key-validation"
+
+describe("API Key Validation", () => {
+	describe("validateApiKeyForByteString", () => {
+		it("should accept valid ASCII characters", () => {
+			expect(() => validateApiKeyForByteString("abc123XYZ", "TestProvider")).not.toThrow()
+			expect(() => validateApiKeyForByteString("test-api-key_123", "TestProvider")).not.toThrow()
+			expect(() => validateApiKeyForByteString("!@#$%^&*()", "TestProvider")).not.toThrow()
+		})
+
+		it("should accept extended ASCII characters (128-255)", () => {
+			// Extended ASCII characters like ñ (241), ü (252)
+			expect(() => validateApiKeyForByteString("test\xF1\xFC", "TestProvider")).not.toThrow()
+			expect(() => validateApiKeyForByteString("key\xFF", "TestProvider")).not.toThrow()
+		})
+
+		it("should reject characters above 255", () => {
+			// Chinese character 中 (20013)
+			expect(() => validateApiKeyForByteString("test中key", "TestProvider")).toThrow(
+				"Invalid TestProvider API key: contains non-ASCII character at position 5",
+			)
+
+			// Emoji 😀 (128512)
+			expect(() => validateApiKeyForByteString("key😀", "TestProvider")).toThrow(
+				"Invalid TestProvider API key: contains non-ASCII character at position 4",
+			)
+
+			// Korean character 한 (54620)
+			expect(() => validateApiKeyForByteString("한글key", "TestProvider")).toThrow(
+				"Invalid TestProvider API key: contains non-ASCII character at position 1",
+			)
+		})
+
+		it("should handle undefined and empty keys", () => {
+			expect(() => validateApiKeyForByteString(undefined, "TestProvider")).not.toThrow()
+			expect(() => validateApiKeyForByteString("", "TestProvider")).not.toThrow()
+		})
+
+		it("should provide clear error messages", () => {
+			expect(() => validateApiKeyForByteString("abc中def", "DeepSeek")).toThrow(
+				"Invalid DeepSeek API key: contains non-ASCII character at position 4. " +
+					"API keys must contain only ASCII characters (character codes 0-255). " +
+					"Please check your API key configuration.",
+			)
+		})
+	})
+
+	describe("validateApiKeyForAscii", () => {
+		it("should accept standard ASCII characters (0-127)", () => {
+			expect(() => validateApiKeyForAscii("abc123XYZ", "TestProvider")).not.toThrow()
+			expect(() => validateApiKeyForAscii("test-api-key_123", "TestProvider")).not.toThrow()
+			expect(() => validateApiKeyForAscii("!@#$%^&*()", "TestProvider")).not.toThrow()
+		})
+
+		it("should reject extended ASCII characters (128-255)", () => {
+			// Extended ASCII character ñ (241)
+			expect(() => validateApiKeyForAscii("test\xF1key", "TestProvider")).toThrow(
+				"Invalid TestProvider API key: contains non-ASCII character at position 5",
+			)
+
+			// Extended ASCII character ü (252)
+			expect(() => validateApiKeyForAscii("key\xFC", "TestProvider")).toThrow(
+				"Invalid TestProvider API key: contains non-ASCII character at position 4",
+			)
+		})
+
+		it("should reject Unicode characters", () => {
+			// Chinese character 中 (20013)
+			expect(() => validateApiKeyForAscii("test中key", "TestProvider")).toThrow(
+				"Invalid TestProvider API key: contains non-ASCII character at position 5",
+			)
+
+			// Emoji 😀 (128512)
+			expect(() => validateApiKeyForAscii("key😀", "TestProvider")).toThrow(
+				"Invalid TestProvider API key: contains non-ASCII character at position 4",
+			)
+		})
+
+		it("should handle undefined and empty keys", () => {
+			expect(() => validateApiKeyForAscii(undefined, "TestProvider")).not.toThrow()
+			expect(() => validateApiKeyForAscii("", "TestProvider")).not.toThrow()
+		})
+
+		it("should provide clear error messages", () => {
+			expect(() => validateApiKeyForAscii("abc\xF1def", "OpenAI")).toThrow(
+				"Invalid OpenAI API key: contains non-ASCII character at position 4. " +
+					"API keys must contain only standard ASCII characters (character codes 0-127). " +
+					"Please check your API key configuration.",
+			)
+		})
+	})
+})
diff --git a/src/api/providers/utils/api-key-validation.ts b/src/api/providers/utils/api-key-validation.ts
@@ -0,0 +1,52 @@
+/**
+ * Validates that an API key contains only valid ByteString characters (0-255).
+ * The OpenAI client library requires API keys to be convertible to ByteString format,
+ * which only supports characters with values 0-255.
+ *
+ * @param apiKey - The API key to validate
+ * @param providerName - The name of the provider for error messaging
+ * @throws Error if the API key contains invalid characters
+ */
+export function validateApiKeyForByteString(apiKey: string | undefined, providerName: string): void {
+	if (!apiKey) {
+		return // No validation needed for undefined/empty keys
+	}
+
+	// Check each character in the API key
+	for (let i = 0; i < apiKey.length; i++) {
+		const charCode = apiKey.charCodeAt(i)
+		if (charCode > 255) {
+			throw new Error(
+				`Invalid ${providerName} API key: contains non-ASCII character at position ${i + 1}. ` +
+					`API keys must contain only ASCII characters (character codes 0-255). ` +
+					`Please check your API key configuration.`,
+			)
+		}
+	}
+}
+
+/**
+ * Validates that an API key contains only standard ASCII characters (0-127).
+ * This is a stricter validation that only allows standard ASCII characters.
+ *
+ * @param apiKey - The API key to validate
+ * @param providerName - The name of the provider for error messaging
+ * @throws Error if the API key contains non-ASCII characters
+ */
+export function validateApiKeyForAscii(apiKey: string | undefined, providerName: string): void {
+	if (!apiKey) {
+		return // No validation needed for undefined/empty keys
+	}
+
+	// Check each character in the API key
+	for (let i = 0; i < apiKey.length; i++) {
+		const charCode = apiKey.charCodeAt(i)
+		if (charCode > 127) {
+			throw new Error(
+				`Invalid ${providerName} API key: contains non-ASCII character at position ${i + 1}. ` +
+					`API keys must contain only standard ASCII characters (character codes 0-127). ` +
+					`Please check your API key configuration.`,
+			)
+		}
+	}
+}
diff --git a/src/api/providers/xai.ts b/src/api/providers/xai.ts
@@ -12,6 +12,7 @@ import { getModelParams } from "../transform/model-params"
 import { DEFAULT_HEADERS } from "./constants"
 import { BaseProvider } from "./base-provider"
 import type { SingleCompletionHandler, ApiHandlerCreateMessageMetadata } from "../index"
+import { validateApiKeyForByteString } from "./utils/api-key-validation"
 
 const XAI_DEFAULT_TEMPERATURE = 0
 
@@ -22,9 +23,15 @@ export class XAIHandler extends BaseProvider implements SingleCompletionHandler
 	constructor(options: ApiHandlerOptions) {
 		super()
 		this.options = options
+
+		const apiKey = this.options.xaiApiKey ?? "not-provided"
+
+		// Validate API key for ByteString compatibility
+		validateApiKeyForByteString(apiKey, "xAI")
+
 		this.client = new OpenAI({
 			baseURL: "https://api.x.ai/v1",
-			apiKey: this.options.xaiApiKey ?? "not-provided",
+			apiKey: apiKey,
 			defaultHeaders: DEFAULT_HEADERS,
 		})
 	}
@@ -78,12 +85,15 @@ export class XAIHandler extends BaseProvider implements SingleCompletionHandler
 			if (chunk.usage) {
 				// Extract detailed token information if available
 				// First check for prompt_tokens_details structure (real API response)
-				const promptDetails = "prompt_tokens_details" in chunk.usage ? chunk.usage.prompt_tokens_details : null;
-				const cachedTokens = promptDetails && "cached_tokens" in promptDetails ? promptDetails.cached_tokens : 0;
+				const promptDetails = "prompt_tokens_details" in chunk.usage ? chunk.usage.prompt_tokens_details : null
+				const cachedTokens = promptDetails && "cached_tokens" in promptDetails ? promptDetails.cached_tokens : 0
 
 				// Fall back to direct fields in usage (used in test mocks)
-				const readTokens = cachedTokens || ("cache_read_input_tokens" in chunk.usage ? (chunk.usage as any).cache_read_input_tokens : 0);
-				const writeTokens = "cache_creation_input_tokens" in chunk.usage ? (chunk.usage as any).cache_creation_input_tokens : 0;
+				const readTokens =
+					cachedTokens ||
+					("cache_read_input_tokens" in chunk.usage ? (chunk.usage as any).cache_read_input_tokens : 0)
+				const writeTokens =
+					"cache_creation_input_tokens" in chunk.usage ? (chunk.usage as any).cache_creation_input_tokens : 0
 
 				yield {
 					type: "usage",

Original file line number	Diff line number	Diff line change
`@@ -22,6 +22,7 @@ import { getModelParams } from "../transform/model-params"`
`22`	`22`
`23`	`23`	`import { BaseProvider } from "./base-provider"`
`24`	`24`	`import type { SingleCompletionHandler, ApiHandlerCreateMessageMetadata } from "../index"`
	`25`	`+import { validateApiKeyForByteString } from "./utils/api-key-validation"`
`25`	`26`
`26`	`27`	`export type OpenAiNativeModel = ReturnType<OpenAiNativeHandler["getModel"]>`
`27`	`28`
`@@ -59,6 +60,10 @@ export class OpenAiNativeHandler extends BaseProvider implements SingleCompletio`
`59`	`60`	`this.options.enableGpt5ReasoningSummary = true`
`60`	`61`	`}`
`61`	`62`	`const apiKey = this.options.openAiNativeApiKey ?? "not-provided"`
	`63`	`+`
	`64`	`+ // Validate API key for ByteString compatibility`
	`65`	`+ validateApiKeyForByteString(apiKey, "OpenAI Native")`
	`66`	`+`
`62`	`67`	`this.client = new OpenAI({ baseURL: this.options.openAiNativeBaseUrl, apiKey })`
`63`	`68`	`}`
`64`	`69`