Skip to content

Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

Python

Validate edited provider API keys during Apply (#1666)

Ali Khokhar8078164b79dc
diff --git a/e2e/test_admin_apply.py b/e2e/test_admin_apply.py
index 5eb30d39..ed5d26b5 100644
--- a/e2e/test_admin_apply.py
+++ b/e2e/test_admin_apply.py
@@ -1,6 +1,7 @@
"""Rendered one-step Admin configuration workflow regressions."""
-from playwright.sync_api import Page, expect
+import pytest
+from playwright.sync_api import Page, Route, expect
def test_apply_is_the_only_config_action_and_retains_invalid_edits(
@@ -39,3 +40,106 @@ def test_apply_is_the_only_config_action_and_retains_invalid_edits(
expect(page.locator("#dirtyState")).to_have_text("1 unsaved change")
expect(apply_button).to_be_enabled()
assert config_mutations == [("POST", "apply")]
+
+
+def test_key_rejection_retains_edits_and_restores_focus(
+ page: Page, admin_base_url: str
+):
+ pending: list[Route] = []
+ page.route("**/admin/api/config/apply", lambda route: pending.append(route))
+ page.goto(f"{admin_base_url}/admin")
+ expect(page.locator("#messageArea")).to_have_text("")
+ key = page.locator("#field-MISTRAL_API_KEY")
+ other = page.locator("#field-NVIDIA_NIM_API_KEY")
+ key.fill("bad-key")
+ other.fill("other-edit")
+ page.get_by_role("button", name="Apply", exact=True).click()
+ expect(page.locator("#messageArea")).to_have_text("Checking API keys…")
+ expect(page.locator("#view-providers")).to_have_attribute("inert", "")
+ expect(page.locator("#applyButton")).to_be_disabled()
+ assert len(pending) == 1
+ submitted = pending[0].request.post_data_json
+ assert isinstance(submitted, dict)
+ assert submitted["values"] == {
+ "MISTRAL_API_KEY": "bad-key",
+ "NVIDIA_NIM_API_KEY": "other-edit",
+ }
+ pending.pop().fulfill(
+ json={
+ "applied": False,
+ "errors": ["Rejected key"],
+ "credential_checks": [
+ {
+ "key": "MISTRAL_API_KEY",
+ "status": "rejected",
+ "message": "Check this API key.",
+ }
+ ],
+ }
+ )
+ expect(key).to_be_focused()
+ expect(key).to_have_attribute("aria-invalid", "true")
+ expect(page.locator("#field-MISTRAL_API_KEY-error")).to_have_text(
+ "Check this API key."
+ )
+ expect(key).to_have_value("bad-key")
+ expect(other).to_have_value("other-edit")
+ expect(page.locator("#dirtyState")).to_have_text("2 unsaved changes")
+ expect(page.locator("#field-OPENROUTER_API_KEY")).to_be_disabled()
+ key.fill("corrected")
+ expect(page.locator("#field-MISTRAL_API_KEY-error")).to_have_count(0)
+ expect(page.locator("#applyButton")).to_be_enabled()
+
+
[email protected]("restart", [False, True])
+def test_unverified_warning_survives_apply(
+ page: Page, admin_base_url: str, restart: bool
+):
+ page.route(
+ "**/admin/api/config/apply",
+ lambda route: route.fulfill(
+ json={
+ "applied": True,
+ "restart": {
+ "required": restart,
+ "automatic": restart,
+ "admin_url": "/admin",
+ },
+ "credential_checks": [
+ {
+ "key": "NVIDIA_NIM_API_KEY",
+ "status": "unverified",
+ "message": "Verification unavailable.",
+ }
+ ],
+ }
+ ),
+ )
+ page.goto(f"{admin_base_url}/admin")
+ expect(page.locator("#messageArea")).to_have_text("")
+ page.locator("#field-NVIDIA_NIM_API_KEY").fill("new-key")
+ page.get_by_role("button", name="Apply", exact=True).click()
+ expect(page.locator("#messageArea")).to_contain_text("Verification unavailable.")
+ if restart:
+ expect(
+ page.get_by_role("link", name="Open Admin", exact=True)
+ ).to_have_attribute("href", "/admin")
+ expect(page.locator("#applyButton")).to_be_disabled()
+ else:
+ expect(page.locator("#dirtyState")).to_have_text("No changes")
+ expect(page.locator("#field-NVIDIA_NIM_API_KEY")).to_be_editable()
+
+
+def test_apply_network_error_unlocks_form_and_keeps_edits(
+ page: Page, admin_base_url: str
+):
+ page.route("**/admin/api/config/apply", lambda route: route.abort())
+ page.goto(f"{admin_base_url}/admin")
+ expect(page.locator("#messageArea")).to_have_text("")
+ key = page.locator("#field-NVIDIA_NIM_API_KEY")
+ key.fill("unsaved-key")
+ page.get_by_role("button", name="Apply", exact=True).click()
+ expect(page.locator("#messageArea")).to_contain_text("Could not apply settings")
+ expect(key).to_have_value("unsaved-key")
+ expect(key).to_be_editable()
+ expect(page.locator("#applyButton")).to_be_enabled()
diff --git a/pyproject.toml b/pyproject.toml
index beed6137..b4caf609 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "5.19.3"
+version = "5.20.0"
description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"
readme = "README.md"
requires-python = ">=3.14.0"
diff --git a/src/free_claude_code/api/admin_static/admin.css b/src/free_claude_code/api/admin_static/admin.css
index 9e8f0eb3..d253a50c 100644
--- a/src/free_claude_code/api/admin_static/admin.css
+++ b/src/free_claude_code/api/admin_static/admin.css
@@ -903,3 +903,15 @@ textarea:focus-visible,
text-align: left;
}
}
+.field-error {
+ color: var(--danger, #ef4444);
+ font-size: 13px;
+}
+
+.field [aria-invalid="true"] {
+ border-color: var(--danger, #ef4444);
+}
+
+#messageArea {
+ white-space: pre-line;
+}
diff --git a/src/free_claude_code/api/admin_static/admin.js b/src/free_claude_code/api/admin_static/admin.js
index 68624786..8b91b31d 100644
--- a/src/free_claude_code/api/admin_static/admin.js
+++ b/src/free_claude_code/api/admin_static/admin.js
@@ -1,5 +1,6 @@
const state = {
config: null,
+ applying: false,
fields: new Map(),
modelOptions: [],
modelComboboxes: new Set(),
@@ -604,6 +605,7 @@ function renderField(field) {
input.addEventListener("change", updateDirtyState);
input.addEventListener("input", () => {
input.dataset.remove = "false";
+ clearCredentialError(input);
});
if (field.type === "optional_model") {
input.addEventListener("blur", () => {
@@ -633,6 +635,7 @@ function renderField(field) {
input.dataset.remove = removing ? "true" : "false";
input.readOnly = removing;
removeButton.textContent = removing ? "Undo removal" : "Remove";
+ clearCredentialError(input);
updateDirtyState();
});
wrapper.appendChild(removeButton);
@@ -885,35 +888,106 @@ function updateDirtyState() {
const count = Object.keys(changedValues()).length;
byId("dirtyState").textContent =
count === 0 ? "No changes" : `${count} unsaved change${count === 1 ? "" : "s"}`;
- byId("applyButton").disabled = count === 0;
+ byId("applyButton").disabled = state.applying || count === 0;
+}
+
+function clearCredentialError(input) {
+ byId(`${input.id}-error`)?.remove();
+ input.removeAttribute("aria-invalid");
+ input.removeAttribute("aria-describedby");
+}
+
+function showCredentialErrors(checks) {
+ let first = null;
+ checks.forEach((check) => {
+ const input = byId(`field-${check.key}`);
+ if (!input) return;
+ clearCredentialError(input);
+ if (check.status !== "rejected") return;
+ const error = document.createElement("div");
+ error.id = `${input.id}-error`;
+ error.className = "field-error";
+ error.textContent = check.message;
+ input.closest(".field").appendChild(error);
+ input.setAttribute("aria-invalid", "true");
+ input.setAttribute("aria-describedby", error.id);
+ first ||= input;
+ });
+ return first;
+}
+
+function setApplying(applying) {
+ state.applying = applying;
+ VIEW_GROUPS.filter((view) => view.id !== "chat").forEach((view) => {
+ byId(`view-${view.id}`).inert = applying;
+ });
+ if (applying) state.modelComboboxes.forEach((combobox) => combobox.close());
+ byId("applyButton").textContent = applying ? "Applying…" : "Apply";
+ updateDirtyState();
}
async function apply() {
- const result = await api("/admin/api/config/apply", {
- method: "POST",
- body: JSON.stringify({ values: changedValues() }),
+ if (state.applying) return;
+ const values = changedValues();
+ if (!Object.keys(values).length) return;
+ const checkingKeys = Object.keys(values).some((key) => {
+ const field = state.fields.get(key);
+ return field?.secret && field.section === "providers" && values[key] !== null;
});
- if (!result.applied) {
- showMessage(result.errors.join("; "), "error");
- return;
- }
- const restart = result.restart || {};
- if (restart.required && restart.automatic) {
- showMessage("Applied. Restarting server...", "ok");
- byId("applyButton").disabled = true;
- setTimeout(() => {
- window.location.href = restart.admin_url || "/admin";
- }, 1600);
- return;
- }
- const pending = restart.required ? restart.fields || [] : result.pending_fields || [];
- await load();
- showMessage(
- pending.length
+ let rejectedField = null;
+ let applied = false;
+ let restarting = false;
+ setApplying(true);
+ showMessage(checkingKeys ? "Checking API keys…" : "Applying…");
+ try {
+ const result = await api("/admin/api/config/apply", {
+ method: "POST",
+ body: JSON.stringify({ values }),
+ });
+ const checks = result.credential_checks || [];
+ if (!result.applied) {
+ rejectedField = showCredentialErrors(checks);
+ showMessage(rejectedField ? "Not applied. Check the highlighted API keys." : result.errors.join("; "), "error");
+ return;
+ }
+ applied = true;
+ const warnings = checks.filter((check) => check.status === "unverified").map((check) =>
+ `${state.fields.get(check.key)?.label || check.key}: ${check.message}`
+ );
+ const restart = result.restart || {};
+ if (restart.required && restart.automatic) {
+ restarting = true;
+ showMessage(["Applied. Restarting server…", ...warnings].join("\n"), warnings.length ? "warn" : "ok");
+ if (warnings.length) {
+ const link = document.createElement("a");
+ link.href = restart.admin_url || "/admin";
+ link.textContent = "Open Admin";
+ byId("messageArea").append(document.createElement("br"), link);
+ } else {
+ setTimeout(() => {
+ window.location.href = restart.admin_url || "/admin";
+ }, 1600);
+ }
+ return;
+ }
+ const pending = restart.required ? restart.fields || [] : result.pending_fields || [];
+ await load();
+ const message = pending.length
? `Applied. Restart fcc-server to use: ${pending.join(", ")}`
- : "Applied",
- "ok",
- );
+ : "Applied";
+ showMessage([message, ...warnings].join("\n"), warnings.length ? "warn" : "ok");
+ } catch (error) {
+ showMessage(applied ? `Applied, but could not reload settings: ${error.message}` : `Could not apply settings: ${error.message}`, "error");
+ } finally {
+ // Keep the old page read-only while its server restarts.
+ setApplying(restarting);
+ if (rejectedField) {
+ navigateToView("providers");
+ rejectedField.closest(".settings-section")?.classList.add("show-advanced");
+ rejectedField.scrollIntoView({ block: "center", behavior: "instant" });
+ rejectedField.focus();
+ }
+ }
}
async function refreshLocalStatus() {
diff --git a/src/free_claude_code/config/admin/persistence.py b/src/free_claude_code/config/admin/persistence.py
index f71e5f9a..12d2d0d7 100644
--- a/src/free_claude_code/config/admin/persistence.py
+++ b/src/free_claude_code/config/admin/persistence.py
@@ -39,6 +39,7 @@ class PreparedAdminUpdate:
errors: tuple[str, ...]
pending_fields: tuple[str, ...]
path: Path
+ changed_keys: tuple[str, ...] = ()
@property
def valid(self) -> bool:
@@ -152,12 +153,25 @@ def prepare_admin_update(
if settings is not None and not errors
else ()
)
+ state = load_value_state()
+ changed_keys = tuple(
+ key
+ for key, submitted in updates.items()
+ if key in FIELD_BY_KEY
+ and not is_locked_source(state[key].source)
+ and (value := normalize_for_env(submitted))
+ and value != MASKED_SECRET
+ and value != state[key].value
+ and key in target_values
+ and target_values[key] == value
+ )
return PreparedAdminUpdate(
target_values=target_values,
settings=settings,
errors=errors,
pending_fields=pending_fields,
path=managed_env_path(),
+ changed_keys=changed_keys,
)
diff --git a/src/free_claude_code/providers/credential_validation.py b/src/free_claude_code/providers/credential_validation.py
new file mode 100644
index 00000000..5dc892c0
--- /dev/null
+++ b/src/free_claude_code/providers/credential_validation.py
@@ -0,0 +1,313 @@
+"""Non-generating credential checks for Admin Apply, independent of inference.
+
+Only documented authenticated endpoints belong here. Public model catalogs and
+management endpoints requiring a different key cannot validate inference keys.
+Failure defaults to unverified; rejection requires provider-specific evidence.
+"""
+
+import asyncio
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from enum import StrEnum
+
+import httpx
+
+from free_claude_code.config.provider_catalog import PROVIDER_CATALOG
+from free_claude_code.config.settings import Settings
+from free_claude_code.core.json_types import JsonValue
+from free_claude_code.providers.runtime.config import string_setting
+
+REQUEST_TIMEOUT = 5.0
+BATCH_TIMEOUT = 10.0
+MAX_CONCURRENCY = 8
+
+
+class CredentialStatus(StrEnum):
+ VERIFIED = "verified"
+ REJECTED = "rejected"
+ UNVERIFIED = "unverified"
+
+
+@dataclass(frozen=True, slots=True)
+class CredentialCheck:
+ key: str
+ status: CredentialStatus
+ message: str
+
+
+def _field(payload: JsonValue, name: str) -> JsonValue:
+ return payload.get(name) if isinstance(payload, Mapping) else None
+
+
+def _list_field(name: str) -> Callable[[JsonValue], bool]:
+ return lambda payload: isinstance(_field(payload, name), list)
+
+
+def _identity(name: str) -> Callable[[JsonValue], bool]:
+ return lambda payload: isinstance(_field(payload, name), str)
+
+
+@dataclass(frozen=True, slots=True)
+class _Probe:
+ provider_id: str
+ path: str
+ accepts: Callable[[JsonValue], bool]
+ rejected_statuses: frozenset[int] = frozenset()
+
+
+_AUTH_401 = frozenset({401})
+_MODELS = _list_field("data")
+
+# Sources document both authenticated reads and (where enabled) rejection codes.
+# https://openrouter.ai/docs/api/api-reference/api-keys/get-current-key
+# https://console.groq.com/docs/errors
+# https://docs.together.ai/reference/models
+# https://api-docs.deepseek.com/quick_start/error_codes/
+# https://api.x.ai/api-docs/openapi.json
+# https://docs.siliconflow.com/cn/api-reference/userinfo/get-user-info
+# https://ai.google.dev/gemini-api/docs/generate-content/api-errors
+# https://github.com/nebius/nebius-physical-ai/blob/main/docs/workbench/token-factory.md
+# https://vercel.com/docs/ai-gateway/sdks-and-apis/rest-api
+# https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/hf_api.py
+# https://docs.cohere.com/reference/list-models
+# https://docs.wafer.ai/serverless/usage-api
+# https://platform.kimi.ai/docs/api/errors
+# https://router.bynara.id/id/docs
+_PROBES = (
+ _Probe(
+ "open_router",
+ "/key",
+ lambda p: isinstance(_field(p, "data"), Mapping),
+ _AUTH_401,
+ ),
+ _Probe("groq", "/models", _MODELS, _AUTH_401),
+ _Probe("together", "/models", lambda p: isinstance(p, list), _AUTH_401),
+ _Probe(
+ "deepseek",
+ "/user/balance",
+ lambda p: (
+ isinstance(_field(p, "is_available"), bool)
+ and isinstance(_field(p, "balance_infos"), list)
+ ),
+ _AUTH_401,
+ ),
+ _Probe("xai", "/api-key", _identity("api_key_id"), _AUTH_401),
+ _Probe(
+ "siliconflow",
+ "/user/info",
+ lambda p: (
+ _field(p, "code") == 20000
+ and _field(p, "status") is True
+ and isinstance(_field(p, "data"), Mapping)
+ ),
+ _AUTH_401,
+ ),
+ _Probe(
+ "gemini",
+ "https://generativelanguage.googleapis.com/v1beta/models?pageSize=1",
+ _list_field("models"),
+ ),
+ _Probe("nebius", "/models", _MODELS, _AUTH_401),
+ _Probe(
+ "vercel",
+ "/credits",
+ lambda p: isinstance(_field(p, "balance"), str | int | float),
+ _AUTH_401,
+ ),
+ _Probe(
+ "huggingface",
+ "https://huggingface.co/api/whoami-v2",
+ _identity("name"),
+ _AUTH_401,
+ ),
+ _Probe(
+ "cohere",
+ "https://api.cohere.com/v1/models?page_size=1",
+ _list_field("models"),
+ frozenset({401, 498}),
+ ),
+ _Probe(
+ "wafer",
+ "https://api.wafer.ai/v1/usage/me?period=1d&endpoint=pass.wafer.ai",
+ _identity("user_id"),
+ _AUTH_401,
+ ),
+ _Probe(
+ "kimi",
+ "/users/me/balance",
+ lambda p: isinstance(
+ _field(_field(p, "data"), "available_balance"), int | float
+ ),
+ _AUTH_401,
+ ),
+ _Probe("nararoute", "/models", _MODELS, _AUTH_401),
+ # Positive evidence only: these errors can also reflect permissions, budget,
+ # token type, or an undocumented response contract. Never reject on failure.
+ # https://docs.deepinfra.com/api-reference/account/me
+ # https://docs.mistral.ai/api/endpoint/models
+ # https://docs.wandb.ai/inference/api-reference
+ # https://docs.github.com/en/rest/users/users#get-the-authenticated-user
+ # https://platform.minimax.io/docs/api-reference/models/openai/list-models
+ # https://novita.ai/docs/api-reference/basic-get-user-balance
+ # https://inference-docs.cerebras.ai/api-reference/models/list-models
+ # https://docs.sambanova.ai/docs/api-reference/models/get-environments-available-model-list-metadata
+ # https://docs.fireworks.ai/api-reference/list-accounts
+ _Probe("deepinfra", "https://api.deepinfra.com/v1/me", _identity("uid")),
+ _Probe("mistral", "/models", _MODELS),
+ _Probe("wandb", "/models", _MODELS),
+ _Probe("github_models", "https://api.github.com/user", _identity("login")),
+ _Probe("minimax", "/models", _MODELS),
+ _Probe(
+ "novita",
+ "https://api.novita.ai/openapi/v1/billing/balance/detail",
+ _identity("availableBalance"),
+ ),
+ _Probe("cerebras", "/models", _MODELS),
+ _Probe("sambanova", "/models", _MODELS),
+ _Probe(
+ "fireworks",
+ "https://api.fireworks.ai/v1/accounts?pageSize=1",
+ _list_field("accounts"),
+ ),
+)
+_PROBE_BY_KEY = {
+ PROVIDER_CATALOG[probe.provider_id].credential_env: probe for probe in _PROBES
+}
+
+
+def _unverified(key: str, message: str) -> CredentialCheck:
+ return CredentialCheck(key, CredentialStatus.UNVERIFIED, message)
+
+
+def _invalid_google_key(payload: JsonValue) -> bool:
+ details = _field(_field(payload, "error"), "details")
+ return isinstance(details, list) and any(
+ _field(detail, "reason") == "API_KEY_INVALID" for detail in details
+ )
+
+
+def _interpret(key: str, probe: _Probe, response: httpx.Response) -> CredentialCheck:
+ try:
+ payload: JsonValue = response.json()
+ except ValueError:
+ return _unverified(
+ key, "Could not verify this key: unexpected provider response."
+ )
+ if response.is_success and probe.accepts(payload):
+ if (
+ probe.provider_id == "deepseek" and _field(payload, "is_available") is False
+ ) or (
+ probe.provider_id == "xai"
+ and any(
+ _field(payload, flag) is True
+ for flag in ("api_key_disabled", "api_key_blocked", "team_blocked")
+ )
+ ):
+ return _unverified(
+ key,
+ "The key was recognized, but the provider reports a billing or access restriction.",
+ )
+ return CredentialCheck(key, CredentialStatus.VERIFIED, "API key accepted.")
+ # Require an API error body; an HTML intermediary's auth challenge is not
+ # evidence that the provider rejected the submitted credential.
+ api_error = isinstance(payload, Mapping) and bool(
+ payload.get("error") or payload.get("message") or payload.get("detail")
+ )
+ # SiliconFlow's /user/info OpenAPI defines 401 JSON as StringData.
+ if probe.provider_id == "siliconflow" and isinstance(payload, str):
+ api_error = True
+ if (api_error and response.status_code in probe.rejected_statuses) or (
+ probe.provider_id == "gemini"
+ and response.status_code == 400
+ and _invalid_google_key(payload)
+ ):
+ return CredentialCheck(
+ key,
+ CredentialStatus.REJECTED,
+ "The provider rejected this API key. Check it or create a new key.",
+ )
+ if response.status_code in {402, 403}:
+ return _unverified(
+ key,
+ "Could not verify this key: check the provider's billing or permissions.",
+ )
+ return _unverified(
+ key, "Could not verify this key with the provider. You can still save it."
+ )
+
+
+async def _check_one(settings: Settings, key: str, probe: _Probe) -> CredentialCheck:
+ descriptor = PROVIDER_CATALOG[probe.provider_id]
+ credential = string_setting(settings, descriptor.credential_attr)
+ if not credential:
+ return _unverified(key, "No API key to verify.")
+ base = (
+ string_setting(settings, descriptor.base_url_attr)
+ or descriptor.default_base_url
+ )
+ if base != descriptor.default_base_url:
+ return _unverified(
+ key, "Key verification is unavailable for this custom endpoint."
+ )
+ assert base is not None
+ url = (
+ probe.path
+ if probe.path.startswith("https://")
+ else base.rstrip("/") + probe.path
+ )
+ headers = {"Accept": "application/json"}
+ if probe.provider_id == "gemini":
+ headers["x-goog-api-key"] = credential
+ else:
+ headers["Authorization"] = f"Bearer {credential}"
+ if probe.provider_id == "github_models":
+ headers["Accept"] = "application/vnd.github+json"
+ if probe.provider_id == "novita":
+ headers["Content-Type"] = "application/json"
+ try:
+ async with asyncio.timeout(REQUEST_TIMEOUT):
+ async with httpx.AsyncClient(
+ proxy=string_setting(settings, descriptor.proxy_attr),
+ timeout=REQUEST_TIMEOUT,
+ follow_redirects=False,
+ ) as client:
+ response = await client.get(url, headers=headers)
+ return _interpret(key, probe, response)
+ except TimeoutError, httpx.RequestError, UnicodeError:
+ return _unverified(key, "Could not reach the provider to verify this key.")
+
+
+async def check_credentials(
+ settings: Settings, changed_keys: tuple[str, ...]
+) -> tuple[CredentialCheck, ...]:
+ """Check distinct edited credentials without touching runtime or model state."""
+ credential_keys = {
+ descriptor.credential_env
+ for descriptor in PROVIDER_CATALOG.values()
+ if not descriptor.local and descriptor.credential_env is not None
+ }
+ keys = tuple(sorted(set(changed_keys) & credential_keys))
+ results = {
+ key: _unverified(
+ key,
+ "The key check timed out."
+ if key in _PROBE_BY_KEY
+ else "Automatic key verification is unavailable for this provider.",
+ )
+ for key in keys
+ }
+ semaphore = asyncio.Semaphore(MAX_CONCURRENCY)
+
+ async def run(key: str, probe: _Probe) -> None:
+ async with semaphore:
+ results[key] = await _check_one(settings, key, probe)
+
+ try:
+ async with asyncio.timeout(BATCH_TIMEOUT):
+ async with asyncio.TaskGroup() as group:
+ for key in keys:
+ if probe := _PROBE_BY_KEY.get(key):
+ group.create_task(run(key, probe))
+ except TimeoutError:
+ pass # Finished results survive; unfinished checks retain their warning.
+ return tuple(results[key] for key in keys)
diff --git a/src/free_claude_code/runtime/application.py b/src/free_claude_code/runtime/application.py
index 88444a22..c3d968e5 100644
--- a/src/free_claude_code/runtime/application.py
+++ b/src/free_claude_code/runtime/application.py
@@ -43,6 +43,10 @@ from free_claude_code.messaging.platforms.ports import (
MessagingRuntime,
)
from free_claude_code.messaging.voice import Transcriber
+from free_claude_code.providers.credential_validation import (
+ CredentialStatus,
+ check_credentials,
+)
from .provider_manager import ProviderRuntimeManager
@@ -187,11 +191,33 @@ class ApplicationRuntime:
async with self._config_lock:
prepared = prepare_admin_update(updates)
if not prepared.valid:
- return prepared.applied_response()
+ return prepared.applied_response() | {"credential_checks": []}
assert prepared.settings is not None
+ checks = await check_credentials(prepared.settings, prepared.changed_keys)
+ check_response: list[JsonObject] = [
+ {
+ "key": check.key,
+ "status": check.status.value,
+ "message": check.message,
+ }
+ for check in checks
+ ]
+ rejected = [
+ check for check in checks if check.status == CredentialStatus.REJECTED
+ ]
+ if rejected:
+ return prepared.validation_response() | {
+ "applied": False,
+ "valid": False,
+ "errors": [f"{check.key}: {check.message}" for check in rejected],
+ "pending_fields": [],
+ "credential_checks": check_response,
+ }
+
if prepared.pending_fields:
result = self._commit_admin_update(prepared)
+ result["credential_checks"] = check_response
restart = self._restart_metadata(
prepared.pending_fields,
prepared.settings,
@@ -214,6 +240,7 @@ class ApplicationRuntime:
)
self._pending_fields = []
result["restart"] = self._restart_metadata((), prepared.settings)
+ result["credential_checks"] = check_response
return result
def admin_status(self) -> JsonObject:
diff --git a/tests/api/test_admin.py b/tests/api/test_admin.py
index 1d0bbff0..3a2629ef 100644
--- a/tests/api/test_admin.py
+++ b/tests/api/test_admin.py
@@ -31,6 +31,15 @@ def _local_client(app):
)
[email protected](autouse=True)
+def _offline_credential_checks(monkeypatch):
+ """These tests exercise config persistence; probe HTTP has its own suite."""
+ monkeypatch.setattr(
+ "free_claude_code.runtime.application.check_credentials",
+ AsyncMock(return_value=()),
+ )
+
+
def _set_home(monkeypatch, tmp_path: Path) -> None:
monkeypatch.setenv("HOME", str(tmp_path))
monkeypatch.setenv("USERPROFILE", str(tmp_path))
diff --git a/tests/config/test_admin_credential_changes.py b/tests/config/test_admin_credential_changes.py
new file mode 100644
index 00000000..3cbbe97d
--- /dev/null
+++ b/tests/config/test_admin_credential_changes.py
@@ -0,0 +1,36 @@
+"""Only effective edits, against saved settings, request credential validation."""
+
+from free_claude_code.config.admin.persistence import (
+ commit_prepared_admin_update,
+ prepare_admin_update,
+)
+from free_claude_code.config.admin.values import MASKED_SECRET
+
+
+def test_changed_keys_exclude_masks_noops_and_removals(monkeypatch):
+ monkeypatch.delenv("GROQ_API_KEY", raising=False)
+ first = prepare_admin_update({"GROQ_API_KEY": " saved-key "})
+ assert first.valid
+ assert first.changed_keys == ("GROQ_API_KEY",)
+ commit_prepared_admin_update(first)
+ # Compare to the saved value even if a running generation has not restarted.
+ for value in ("saved-key", " saved-key ", MASKED_SECRET, "", " ", None):
+ prepared = prepare_admin_update({"GROQ_API_KEY": value})
+ assert prepared.valid
+ assert prepared.changed_keys == ()
+ changed = prepare_admin_update(
+ {"GROQ_API_KEY": "new-key", "GROQ_PROXY": "http://localhost:8080"}
+ )
+ assert "GROQ_API_KEY" in changed.changed_keys
+ assert changed.settings is not None
+ assert changed.settings.groq_api_key == "new-key"
+ assert changed.settings.groq_proxy == "http://localhost:8080"
+
+
+def test_process_locked_key_is_not_a_change(monkeypatch):
+ monkeypatch.setenv("GROQ_API_KEY", "process-key")
+ prepared = prepare_admin_update({"GROQ_API_KEY": "submitted-key"})
+ assert prepared.valid
+ assert prepared.changed_keys == ()
+ assert prepared.settings is not None
+ assert prepared.settings.groq_api_key == "process-key"
diff --git a/tests/providers/test_credential_validation.py b/tests/providers/test_credential_validation.py
new file mode 100644
index 00000000..50c339cc
--- /dev/null
+++ b/tests/providers/test_credential_validation.py
@@ -0,0 +1,337 @@
+"""Credential evidence must not consume inference or reject ambiguous failures."""
+
+import asyncio
+
+import httpx
+import pytest
+
+from free_claude_code.config.provider_catalog import PROVIDER_CATALOG
+from free_claude_code.config.settings import Settings
+from free_claude_code.providers import credential_validation as validation
+
+# Minimal published response shapes, independent of the implementation registry.
+CASES = [
+ (
+ "open_router",
+ "https://openrouter.ai/api/v1/key",
+ {"data": {"label": "key"}},
+ 401,
+ ),
+ ("groq", "https://api.groq.com/openai/v1/models", {"data": []}, 401),
+ ("together", "https://api.together.ai/v1/models", [], 401),
+ (
+ "deepseek",
+ "https://api.deepseek.com/user/balance",
+ {"is_available": True, "balance_infos": []},
+ 401,
+ ),
+ ("xai", "https://api.x.ai/v1/api-key", {"api_key_id": "id"}, 401),
+ (
+ "siliconflow",
+ "https://api.siliconflow.com/v1/user/info",
+ {"code": 20000, "status": True, "data": {}},
+ 401,
+ ),
+ (
+ "gemini",
+ "https://generativelanguage.googleapis.com/v1beta/models?pageSize=1",
+ {"models": []},
+ 400,
+ ),
+ ("nebius", "https://api.tokenfactory.nebius.com/v1/models", {"data": []}, 401),
+ (
+ "vercel",
+ "https://ai-gateway.vercel.sh/v1/credits",
+ {"balance": "0", "total_used": "1"},
+ 401,
+ ),
+ ("huggingface", "https://huggingface.co/api/whoami-v2", {"name": "user"}, 401),
+ ("cohere", "https://api.cohere.com/v1/models?page_size=1", {"models": []}, 498),
+ (
+ "wafer",
+ "https://api.wafer.ai/v1/usage/me?period=1d&endpoint=pass.wafer.ai",
+ {"user_id": "id"},
+ 401,
+ ),
+ (
+ "kimi",
+ "https://api.moonshot.ai/v1/users/me/balance",
+ {"data": {"available_balance": 0}},
+ 401,
+ ),
+ ("nararoute", "https://router.bynara.id/v1/models", {"data": []}, 401),
+ (
+ "deepinfra",
+ "https://api.deepinfra.com/v1/me",
+ {"uid": "id", "email": None},
+ None,
+ ),
+ ("mistral", "https://api.mistral.ai/v1/models", {"data": []}, None),
+ ("wandb", "https://api.inference.wandb.ai/v1/models", {"data": []}, None),
+ ("github_models", "https://api.github.com/user", {"login": "user"}, None),
+ ("minimax", "https://api.minimax.io/v1/models", {"data": []}, None),
+ (
+ "novita",
+ "https://api.novita.ai/openapi/v1/billing/balance/detail",
+ {"availableBalance": "0"},
+ None,
+ ),
+ ("cerebras", "https://api.cerebras.ai/v1/models", {"data": []}, None),
+ ("sambanova", "https://api.sambanova.ai/v1/models", {"data": []}, None),
+ (
+ "fireworks",
+ "https://api.fireworks.ai/v1/accounts?pageSize=1",
+ {"accounts": []},
+ None,
+ ),
+]
+
+
+def _settings(provider_id):
+ descriptor = PROVIDER_CATALOG[provider_id]
+ assert descriptor.credential_attr is not None
+ return Settings.model_construct(
+ _fields_set=set(), **{descriptor.credential_attr: "secret-not-a-known-format"}
+ )
+
+
+def _mock_http(monkeypatch, handler):
+ clients = []
+ real_client = httpx.AsyncClient
+
+ def factory(**kwargs):
+ client = real_client(**kwargs, transport=httpx.MockTransport(handler))
+ clients.append(client)
+ return client
+
+ monkeypatch.setattr(validation.httpx, "AsyncClient", factory)
+ return clients
+
+
[email protected](("provider_id", "url", "payload", "rejection"), CASES)
+async def test_documented_probe_acceptance_and_rejection(
+ monkeypatch, provider_id, url, payload, rejection
+):
+ requests = []
+ status = 200
+ body = payload
+
+ def respond(request):
+ requests.append(request)
+ assert request.method == "GET"
+ assert str(request.url) == url
+ header = "x-goog-api-key" if provider_id == "gemini" else "Authorization"
+ expected = (
+ "secret-not-a-known-format"
+ if provider_id == "gemini"
+ else "Bearer secret-not-a-known-format"
+ )
+ assert request.headers[header] == expected
+ assert "secret-not-a-known-format" not in str(request.url)
+ assert not request.content
+ return httpx.Response(status, json=body)
+
+ clients = _mock_http(monkeypatch, respond)
+ key = PROVIDER_CATALOG[provider_id].credential_env
+ assert key is not None
+ result = await validation.check_credentials(_settings(provider_id), (key, key))
+ assert result[0].status == validation.CredentialStatus.VERIFIED
+ assert len(requests) == 1
+ assert all(client.is_closed for client in clients)
+
+ status = rejection or 401
+ body = {"error": {"message": "secret-not-a-known-format"}}
+ if provider_id == "gemini":
+ body = {"error": {"details": [{"reason": "API_KEY_INVALID"}]}}
+ if provider_id == "siliconflow":
+ body = "Invalid token" # The documented StringData error body.
+ result = await validation.check_credentials(_settings(provider_id), (key,))
+ assert result[0].status == (
+ validation.CredentialStatus.REJECTED
+ if rejection
+ else validation.CredentialStatus.UNVERIFIED
+ )
+ assert "secret-not-a-known-format" not in repr(result)
+ assert len(requests) == 2
+ assert all(client.is_closed for client in clients)
+
+
[email protected]("status", [400, 402, 403, 404, 429, 500, 503])
+async def test_ambiguous_errors_warn_without_retry(monkeypatch, status, caplog):
+ requests = []
+
+ def respond(request):
+ requests.append(request)
+ return httpx.Response(status, json={"error": "secret-not-a-known-format"})
+
+ _mock_http(monkeypatch, respond)
+ result = await validation.check_credentials(_settings("groq"), ("GROQ_API_KEY",))
+ assert result[0].status == validation.CredentialStatus.UNVERIFIED
+ assert len(requests) == 1
+ assert "secret-not-a-known-format" not in caplog.text
+
+
[email protected]("status", [200, 401, 302])
+async def test_non_api_responses_do_not_verify_or_reject(monkeypatch, status):
+ _mock_http(
+ monkeypatch,
+ lambda request: httpx.Response(
+ status,
+ text="<html>Sign in</html>",
+ headers={"Location": "https://other.invalid/"},
+ ),
+ )
+ result = await validation.check_credentials(_settings("groq"), ("GROQ_API_KEY",))
+ assert result[0].status == validation.CredentialStatus.UNVERIFIED
+
+
+async def test_unsupported_shared_credentials_never_send_http(monkeypatch):
+ def unexpected(request):
+ pytest.fail("Public catalogs must not be used to verify a credential")
+
+ _mock_http(monkeypatch, unexpected)
+ supported = {PROVIDER_CATALOG[row[0]].credential_env for row in CASES}
+ all_keys = {d.credential_env for d in PROVIDER_CATALOG.values() if d.credential_env}
+ keys = tuple(all_keys - supported)
+ assert len(keys) == 20
+ result = await validation.check_credentials(
+ Settings.model_construct(), (*keys, "OPENCODE_API_KEY", "MODEL")
+ )
+ assert len(result) == 20
+ assert all(
+ check.status == validation.CredentialStatus.UNVERIFIED for check in result
+ )
+
+
+async def test_batch_timeout_preserves_finished_rejection_and_closes_clients(
+ monkeypatch,
+):
+ async def respond(request):
+ if request.url.host == "api.groq.com":
+ return httpx.Response(401, json={"error": "invalid key"})
+ await asyncio.Event().wait()
+ raise AssertionError("unreachable")
+
+ clients = _mock_http(monkeypatch, respond)
+ monkeypatch.setattr(validation, "MAX_CONCURRENCY", 1)
+ monkeypatch.setattr(validation, "BATCH_TIMEOUT", 0.1)
+ settings = Settings.model_construct(groq_api_key="key", open_router_api_key="key")
+ results = await validation.check_credentials(
+ settings, ("GROQ_API_KEY", "OPENROUTER_API_KEY")
+ )
+ assert [r.status for r in results] == [
+ validation.CredentialStatus.REJECTED,
+ validation.CredentialStatus.UNVERIFIED,
+ ]
+ assert len(clients) == 2
+ assert all(client.is_closed for client in clients)
+
+
+async def test_external_cancellation_propagates_and_closes_clients(monkeypatch):
+ started = asyncio.Event()
+
+ async def respond(request):
+ started.set()
+ await asyncio.Event().wait()
+ raise AssertionError("unreachable")
+
+ clients = _mock_http(monkeypatch, respond)
+ task = asyncio.create_task(
+ validation.check_credentials(_settings("groq"), ("GROQ_API_KEY",))
+ )
+ await started.wait()
+ task.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await task
+ assert all(client.is_closed for client in clients)
+
+
+async def test_connection_failure_is_safe_and_does_not_retry(monkeypatch):
+ calls = 0
+
+ def respond(request):
+ nonlocal calls
+ calls += 1
+ raise httpx.ConnectError("secret-not-a-known-format", request=request)
+
+ clients = _mock_http(monkeypatch, respond)
+ results = await validation.check_credentials(_settings("groq"), ("GROQ_API_KEY",))
+ assert results[0].status == validation.CredentialStatus.UNVERIFIED
+ assert "secret-not-a-known-format" not in repr(results)
+ assert calls == 1
+ assert all(client.is_closed for client in clients)
+
+
+ ("provider_id", "payload"),
+ [
+ ("deepseek", {"is_available": False, "balance_infos": []}),
+ ("xai", {"api_key_id": "id", "team_blocked": True}),
+ ],
+)
+async def test_recognized_restricted_key_warns_instead_of_rejecting(
+ monkeypatch, provider_id, payload
+):
+ _mock_http(monkeypatch, lambda request: httpx.Response(200, json=payload))
+ key = PROVIDER_CATALOG[provider_id].credential_env
+ assert key is not None
+ result = await validation.check_credentials(_settings(provider_id), (key,))
+ assert result[0].status == validation.CredentialStatus.UNVERIFIED
+ assert "recognized" in result[0].message
+
+
+async def test_checks_are_concurrent_but_bounded(monkeypatch):
+ first_wave = asyncio.Event()
+ release = asyncio.Event()
+ active = 0
+ peak = 0
+ started = []
+
+ async def check(settings, key, probe):
+ nonlocal active, peak
+ active += 1
+ peak = max(peak, active)
+ started.append(key)
+ if active == 2:
+ first_wave.set()
+ await release.wait()
+ active -= 1
+ return validation.CredentialCheck(
+ key, validation.CredentialStatus.VERIFIED, "accepted"
+ )
+
+ monkeypatch.setattr(validation, "_check_one", check)
+ monkeypatch.setattr(validation, "MAX_CONCURRENCY", 2)
+ task = asyncio.create_task(
+ validation.check_credentials(
+ Settings.model_construct(),
+ ("GROQ_API_KEY", "MISTRAL_API_KEY", "OPENROUTER_API_KEY"),
+ )
+ )
+ await first_wave.wait()
+ assert len(started) == 2
+ release.set()
+ results = await task
+ assert len(results) == 3
+ assert peak == 2
+
+
+async def test_programming_errors_do_not_become_permission_to_save(monkeypatch):
+ def broken(request):
+ raise RuntimeError("unexpected bug")
+
+ clients = _mock_http(monkeypatch, broken)
+ with pytest.raises(ExceptionGroup) as error:
+ await validation.check_credentials(_settings("groq"), ("GROQ_API_KEY",))
+ assert isinstance(error.value.exceptions[0], RuntimeError)
+ assert all(client.is_closed for client in clients)
diff --git a/tests/runtime/test_application_runtime.py b/tests/runtime/test_application_runtime.py
index d5e47393..96b21a40 100644
--- a/tests/runtime/test_application_runtime.py
+++ b/tests/runtime/test_application_runtime.py
@@ -1,6 +1,7 @@
import asyncio
import logging
from collections.abc import AsyncIterator
+from dataclasses import replace
from pathlib import Path
from unittest.mock import AsyncMock, MagicMock, patch
@@ -27,6 +28,10 @@ from free_claude_code.messaging.platforms.ports import (
from free_claude_code.messaging.session import SessionStore
from free_claude_code.messaging.workflow import MessagingWorkflow
from free_claude_code.providers.base import BaseProvider
+from free_claude_code.providers.credential_validation import (
+ CredentialCheck,
+ CredentialStatus,
+)
from free_claude_code.providers.runtime import ProviderRuntime
from free_claude_code.runtime.application import ApplicationRuntime
from free_claude_code.runtime.provider_manager import ProviderRuntimeManager
@@ -495,6 +500,81 @@ async def test_restart_required_apply_commits_without_hot_publication(tmp_path)
await manager.close()
[email protected]("pending", [(), ("PORT",)])
[email protected]("status", list(CredentialStatus))
+async def test_credential_checks_gate_both_apply_paths(tmp_path, pending, status):
+ factory = TrackingFactory()
+ manager = ProviderRuntimeManager(
+ _settings("nvidia_nim/old"), runtime_factory=factory
+ )
+ runtime = ApplicationRuntime(manager, transcriber=None)
+ prepared = replace(
+ _prepared(_settings("nvidia_nim/new"), tmp_path, pending_fields=pending),
+ changed_keys=("GROQ_API_KEY",),
+ )
+ checks = (
+ CredentialCheck("GROQ_API_KEY", status, "Safe result"),
+ CredentialCheck("OPENROUTER_API_KEY", CredentialStatus.VERIFIED, "Accepted"),
+ )
+ with (
+ patch(
+ "free_claude_code.runtime.application.prepare_admin_update",
+ return_value=prepared,
+ ),
+ patch(
+ "free_claude_code.runtime.application.check_credentials",
+ AsyncMock(return_value=checks),
+ ) as check,
+ patch(
+ "free_claude_code.runtime.application.commit_prepared_admin_update",
+ return_value=_applied_response(pending),
+ ) as commit,
+ ):
+ result = await runtime.apply_admin_config({"GROQ_API_KEY": "new"})
+ check.assert_awaited_once_with(prepared.settings, prepared.changed_keys)
+ assert result["credential_checks"] == [
+ {"key": check.key, "status": check.status.value, "message": check.message}
+ for check in checks
+ ]
+ if status == CredentialStatus.REJECTED:
+ commit.assert_not_called()
+ assert result["applied"] is False
+ assert manager.current_generation_id == 1
+ else:
+ commit.assert_called_once_with(prepared)
+ assert result["applied"] is True
+ assert manager.current_generation_id == (1 if pending else 2)
+ await manager.close()
+
+
+async def test_cancelled_credential_check_never_commits(tmp_path):
+ manager = ProviderRuntimeManager(_settings("nvidia_nim/old"))
+ runtime = ApplicationRuntime(manager, transcriber=None)
+ prepared = replace(
+ _prepared(_settings("nvidia_nim/new"), tmp_path), changed_keys=("GROQ_API_KEY",)
+ )
+ with (
+ patch(
+ "free_claude_code.runtime.application.prepare_admin_update",
+ return_value=prepared,
+ ),
+ patch(
+ "free_claude_code.runtime.application.check_credentials",
+ AsyncMock(side_effect=asyncio.CancelledError),
+ ),
+ patch(
+ "free_claude_code.runtime.application.commit_prepared_admin_update"
+ ) as commit,
+ pytest.raises(asyncio.CancelledError),
+ ):
+ await runtime.apply_admin_config({"GROQ_API_KEY": "new"})
+ commit.assert_not_called()
+ assert manager.current_generation_id == 1
+ await manager.close()
+
+
@pytest.mark.asyncio
async def test_close_drains_messaging_before_transcriber_and_is_idempotent() -> None:
events: list[str] = []
diff --git a/uv.lock b/uv.lock
index 92b2b086..73ad1cb7 100644
--- a/uv.lock
+++ b/uv.lock
@@ -598,7 +598,7 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "5.19.3"
+version = "5.20.0"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },