Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: gate saved Connection keys on a stamped key purpose, not the key name (#14824)

Daniel Han19ca9c350809
diff --git a/studio/backend/auth/storage.py b/studio/backend/auth/storage.py
index ff4ce8c972f..b3577b00d78 100644
--- a/studio/backend/auth/storage.py
+++ b/studio/backend/auth/storage.py
@@ -334,13 +334,21 @@ def get_connection(*, check_same_thread: bool = True) -> sqlite3.Connection:
last_used_at TEXT,
expires_at TEXT,
is_active INTEGER NOT NULL DEFAULT 1,
- is_internal INTEGER NOT NULL DEFAULT 0
+ is_internal INTEGER NOT NULL DEFAULT 0,
+ purpose TEXT
);
"""
)
api_key_columns = {row["name"] for row in conn.execute("PRAGMA table_info(api_keys)")}
if "is_internal" not in api_key_columns:
conn.execute("ALTER TABLE api_keys ADD COLUMN is_internal INTEGER NOT NULL DEFAULT 0")
+ if "purpose" not in api_key_columns:
+ # Set only at mint and never editable; rows predating it stay NULL and carry no authority.
+ try:
+ conn.execute("ALTER TABLE api_keys ADD COLUMN purpose TEXT")
+ except sqlite3.OperationalError as exc:
+ if "duplicate column" not in str(exc).lower():
+ raise
conn.execute(
"""
CREATE TABLE IF NOT EXISTS app_secrets (
@@ -1754,6 +1762,8 @@ DEEP_RESEARCH_WORKFLOW_KEY_NAME = "deep-research workflow"
# What `unsloth start` mints for its coding agents (unsloth_cli/commands/start.py). Only a desktop
# session can create a key with this name, and only the owner's may spend saved Connections.
UNSLOTH_START_API_KEY_NAME = "Coding agents (unsloth start)"
+# Authority follows this mint stamp, not the name: older Studios let any caller pick the name.
+UNSLOTH_START_API_KEY_PURPOSE = "unsloth_start"
def create_api_key(
@@ -1763,6 +1773,7 @@ def create_api_key(
internal: bool = False,
expect_gen: Optional[str] = None,
account_id: Optional[str] = None,
+ purpose: Optional[str] = None,
) -> Tuple[str, dict]:
"""Create a new API key for *username*. Returns ``(raw_key, row_dict)`` where *raw_key* is shown to
the user exactly once; the database only stores the PBKDF2 hash. Pass ``internal=True`` for keys
@@ -1787,8 +1798,8 @@ def create_api_key(
account_id = _managed_account_id(conn, username)
conn.execute(
"""
- INSERT INTO api_keys (username, key_prefix, key_hash, name, created_at, expires_at, is_internal, account_id)
- VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+ INSERT INTO api_keys (username, key_prefix, key_hash, name, created_at, expires_at, is_internal, account_id, purpose)
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
""",
(
username,
@@ -1799,6 +1810,7 @@ def create_api_key(
expires_at,
1 if internal else 0,
account_id,
+ purpose,
),
)
if account_id is not None:
@@ -1827,7 +1839,7 @@ def list_api_keys(
cur = conn.execute(
f"""
SELECT id, username, key_prefix, name, created_at, last_used_at,
- expires_at, is_active, is_internal
+ expires_at, is_active, is_internal, purpose
FROM api_keys
WHERE {scope}{internal}
ORDER BY created_at DESC
@@ -1991,7 +2003,7 @@ def validate_api_key_account(raw_key: str, *, touch: bool = True) -> Optional[Tu
touch = False
cur = conn.execute(
f"""
- SELECT k.id, k.username, k.name, k.is_active, k.expires_at,
+ SELECT k.id, k.username, k.name, k.purpose, k.is_active, k.expires_at,
u.account_id, u.role, u.is_active AS account_active,
COALESCE(u.account_jwt_secret, u.jwt_secret) AS jwt_secret
FROM api_keys k JOIN auth_user u ON u.username = k.username
@@ -2036,6 +2048,7 @@ def validate_api_key_account(raw_key: str, *, touch: bool = True) -> Optional[Tu
"is_active": int(row["account_active"]),
"expires_at": row["expires_at"],
"key_name": row["name"],
+ "key_purpose": row["purpose"],
}
return record, secret
finally:
diff --git a/studio/backend/models/auth.py b/studio/backend/models/auth.py
index 76e2d370d6e..71b19834a8e 100644
--- a/studio/backend/models/auth.py
+++ b/studio/backend/models/auth.py
@@ -112,6 +112,8 @@ class ApiKeyResponse(BaseModel):
last_used_at: Optional[str] = None
expires_at: Optional[str] = None
is_active: bool
+ # Read-only: set by the server at mint ("unsloth_start" for the desktop `unsloth start` key).
+ purpose: Optional[str] = None
class CreateApiKeyResponse(BaseModel):
diff --git a/studio/backend/routes/auth.py b/studio/backend/routes/auth.py
index 85bd6db0be5..d112c172062 100644
--- a/studio/backend/routes/auth.py
+++ b/studio/backend/routes/auth.py
@@ -819,6 +819,7 @@ def _row_to_api_key_response(row: dict) -> ApiKeyResponse:
last_used_at = row.get("last_used_at"),
expires_at = row.get("expires_at"),
is_active = bool(row["is_active"]),
+ purpose = row.get("purpose"),
)
@@ -865,6 +866,9 @@ async def create_api_key(
expires_at = expires_at,
expect_gen = generation,
account_id = _key_account_scope(),
+ purpose = storage.UNSLOTH_START_API_KEY_PURPOSE
+ if payload.name == storage.UNSLOTH_START_API_KEY_NAME
+ else None,
)
except storage.CredentialRotated:
raise HTTPException(
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index e0be9c9369a..099f93f089f 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -4022,7 +4022,8 @@ def _request_may_use_saved_provider_key(request: Any) -> bool:
verified = auth_storage.validate_api_key_account(token, touch = False)
if verified is None or verified[0].get("role") not in (None, "owner"):
return False
- if verified[0].get("key_name") != auth_storage.UNSLOTH_START_API_KEY_NAME:
+ # The purpose, not the name: a pre-reservation namesake carries no purpose.
+ if verified[0].get("key_purpose") != auth_storage.UNSLOTH_START_API_KEY_PURPOSE:
return False
return not auth_storage.is_internal_api_key(token)
except Exception:
@@ -32624,26 +32625,36 @@ def _connection_model_ref(model: Any) -> Optional[tuple[str, str]]:
# Provider replay metadata agent clients drop: Gemini 3 answers 400 to a functionCall without its
# thoughtSignature (tool call extra_content), and Anthropic to a tool continuation without its signed
-# thinking (message extra_content). Keep both by the tool ids the client echoes back.
+# thinking (message extra_content). Keep both by echoed tool id, capped per subject and overall.
_CONNECTION_TOOL_EXTRAS: collections.OrderedDict = collections.OrderedDict()
_CONNECTION_TOOL_EXTRAS_MAX = 4096
+_CONNECTION_TOOL_EXTRAS_SUBJECTS_MAX = 64
_CONNECTION_TOOL_EXTRAS_LOCK = threading.Lock()
def _remember_connection_extra(subject: Optional[str], kind: str, tool_id: Any, extra: Any) -> None:
if not isinstance(tool_id, str) or not tool_id or not isinstance(extra, dict) or not extra:
return
- key = (subject or "", kind, tool_id)
+ key = (kind, tool_id)
with _CONNECTION_TOOL_EXTRAS_LOCK:
- _CONNECTION_TOOL_EXTRAS[key] = extra
- _CONNECTION_TOOL_EXTRAS.move_to_end(key)
- while len(_CONNECTION_TOOL_EXTRAS) > _CONNECTION_TOOL_EXTRAS_MAX:
+ extras = _CONNECTION_TOOL_EXTRAS.setdefault(subject or "", collections.OrderedDict())
+ _CONNECTION_TOOL_EXTRAS.move_to_end(subject or "")
+ extras[key] = extra
+ extras.move_to_end(key)
+ while len(extras) > _CONNECTION_TOOL_EXTRAS_MAX:
+ extras.popitem(last = False)
+ while len(_CONNECTION_TOOL_EXTRAS) > _CONNECTION_TOOL_EXTRAS_SUBJECTS_MAX:
_CONNECTION_TOOL_EXTRAS.popitem(last = False)
def _connection_extra(subject: Optional[str], kind: str, tool_id: Any) -> Optional[dict]:
with _CONNECTION_TOOL_EXTRAS_LOCK:
- return _CONNECTION_TOOL_EXTRAS.get((subject or "", kind, tool_id))
+ extras = _CONNECTION_TOOL_EXTRAS.get(subject or "")
+ extra = extras.get((kind, tool_id)) if extras is not None else None
+ if extra is not None:
+ # A replay keeps the account recent, so a new account does not evict its history.
+ _CONNECTION_TOOL_EXTRAS.move_to_end(subject or "")
+ return extra
class _ConnectionExtrasRecorder:
diff --git a/studio/backend/tests/test_connection_model_routes.py b/studio/backend/tests/test_connection_model_routes.py
index 1c0c14fd721..1b49ff7107e 100644
--- a/studio/backend/tests/test_connection_model_routes.py
+++ b/studio/backend/tests/test_connection_model_routes.py
@@ -124,7 +124,14 @@ def v1(monkeypatch):
inf.auth_storage,
"validate_api_key_account",
lambda raw, touch = True: {
- USER_KEY: ({"role": "owner", "key_name": "Coding agents (unsloth start)"}, "s"),
+ USER_KEY: (
+ {
+ "role": "owner",
+ "key_name": "Coding agents (unsloth start)",
+ "key_purpose": "unsloth_start",
+ },
+ "s",
+ ),
SCRIPT_KEY: ({"role": "owner", "key_name": "my script"}, "s"),
}.get(raw),
)
@@ -532,6 +539,44 @@ def test_a_signature_is_only_replayed_for_its_own_account(v1):
assert "extra_content" not in messages[0]["tool_calls"][0]
+def test_one_accounts_signatures_cannot_evict_anothers(v1, monkeypatch):
+ import routes.inference as inf
+
+ monkeypatch.setattr(inf, "_CONNECTION_TOOL_EXTRAS_MAX", 8)
+ inf._remember_connection_extra("alice", "call", "call_1", SIGNED["extra_content"])
+ for i in range(20):
+ inf._remember_connection_extra("bob", "call", f"call_{i}", {"n": i})
+
+ assert inf._connection_extra("alice", "call", "call_1") == SIGNED["extra_content"]
+ assert inf._connection_extra("bob", "call", "call_0") is None
+ assert inf._connection_extra("bob", "call", "call_19") == {"n": 19}
+
+
+def test_signature_cache_bounds_the_number_of_accounts(v1, monkeypatch):
+ import routes.inference as inf
+
+ monkeypatch.setattr(inf, "_CONNECTION_TOOL_EXTRAS_SUBJECTS_MAX", 3)
+ for i in range(5):
+ inf._remember_connection_extra(f"user{i}", "call", "call_1", {"n": i})
+
+ assert len(inf._CONNECTION_TOOL_EXTRAS) == 3
+ assert inf._connection_extra("user0", "call", "call_1") is None
+ assert inf._connection_extra("user4", "call", "call_1") == {"n": 4}
+
+
+def test_signature_cache_replay_keeps_an_account_recent(v1, monkeypatch):
+ import routes.inference as inf
+
+ monkeypatch.setattr(inf, "_CONNECTION_TOOL_EXTRAS_SUBJECTS_MAX", 3)
+ for i in range(3):
+ inf._remember_connection_extra(f"user{i}", "call", "call_1", {"n": i})
+ assert inf._connection_extra("user0", "call", "call_1") == {"n": 0}
+ inf._remember_connection_extra("user3", "call", "call_1", {"n": 3})
+
+ assert inf._connection_extra("user0", "call", "call_1") == {"n": 0}
+ assert inf._connection_extra("user1", "call", "call_1") is None
+
+
def test_chat_completions_without_stream_returns_one_completion_object(v1):
FakeExternalClient.tool_extra = SIGNED
resp = v1.post(
diff --git a/studio/backend/tests/test_external_confirm_gate_and_saved_keys.py b/studio/backend/tests/test_external_confirm_gate_and_saved_keys.py
index 90045284c3f..23510caf5e1 100644
--- a/studio/backend/tests/test_external_confirm_gate_and_saved_keys.py
+++ b/studio/backend/tests/test_external_confirm_gate_and_saved_keys.py
@@ -341,12 +341,17 @@ def test_a_third_party_key_never_unlocks_a_saved_connection(monkeypatch):
assert seen == [False]
+START = "Coding agents (unsloth start)"
+
+
@pytest.mark.parametrize(
"record, allowed",
[
- ({"role": "owner", "key_name": "Coding agents (unsloth start)"}, True),
- ({"role": "owner", "key_name": "my script"}, False),
- ({"role": "member", "key_name": "Coding agents (unsloth start)"}, False),
+ ({"role": "owner", "key_name": START, "key_purpose": "unsloth_start"}, True),
+ ({"role": "owner", "key_name": "my script", "key_purpose": None}, False),
+ # Named like the start key before the name was reserved, but never stamped.
+ ({"role": "owner", "key_name": START, "key_purpose": None}, False),
+ ({"role": "member", "key_name": START, "key_purpose": "unsloth_start"}, False),
],
)
def test_only_the_owners_unsloth_start_key_unlocks_a_saved_connection(monkeypatch, record, allowed):
diff --git a/studio/backend/tests/test_unsloth_start_api_key.py b/studio/backend/tests/test_unsloth_start_api_key.py
index 0eb23feeb9c..406f236bd90 100644
--- a/studio/backend/tests/test_unsloth_start_api_key.py
+++ b/studio/backend/tests/test_unsloth_start_api_key.py
@@ -58,15 +58,36 @@ def test_only_a_desktop_session_can_mint_the_unsloth_start_key(client):
minted = _mint(client, create_access_token(owner, desktop = True), START)
assert minted.status_code == 200, minted.text
assert minted.json()["api_key"]["name"] == START
+ assert minted.json()["api_key"]["purpose"] == storage.UNSLOTH_START_API_KEY_PURPOSE
+
+
+def test_the_purpose_is_stamped_by_the_server_not_the_caller(client):
+ owner = storage.DEFAULT_ADMIN_USERNAME
+ user_key, _row = storage.create_api_key(owner, name = "my script")
+ for bearer in (user_key, create_access_token(owner), create_access_token(owner, desktop = True)):
+ minted = client.post(
+ "/api/auth/api-keys",
+ headers = {"Authorization": f"Bearer {bearer}"},
+ json = {"name": "other", "purpose": storage.UNSLOTH_START_API_KEY_PURPOSE},
+ )
+ assert minted.status_code == 200, minted.text
+ assert minted.json()["api_key"]["purpose"] is None
+ listed = client.get(
+ "/api/auth/api-keys", headers = {"Authorization": f"Bearer {create_access_token(owner)}"}
+ )
+ assert {k["purpose"] for k in listed.json()["api_keys"]} == {None}
def test_only_the_unsloth_start_key_may_use_a_saved_connection():
from routes import inference as inf
owner = storage.DEFAULT_ADMIN_USERNAME
- start_key, _ = storage.create_api_key(owner, name = START)
+ purpose = storage.UNSLOTH_START_API_KEY_PURPOSE
+ start_key, _ = storage.create_api_key(owner, name = START, purpose = purpose)
user_key, _ = storage.create_api_key(owner, name = "my script")
- internal_key, _ = storage.create_api_key(owner, name = START, internal = True)
+ internal_key, _ = storage.create_api_key(owner, name = START, internal = True, purpose = purpose)
+ # A row any caller could mint under this name before it was reserved: same name, no purpose.
+ legacy_key, _ = storage.create_api_key(owner, name = START)
def allowed(raw):
return inf._request_may_use_saved_provider_key(
@@ -76,9 +97,44 @@ def test_only_the_unsloth_start_key_may_use_a_saved_connection():
assert allowed(start_key) is True
assert allowed(user_key) is False
assert allowed(internal_key) is False
+ assert allowed(legacy_key) is False
assert allowed("sk-unsloth-0000000000000000") is False
+def test_a_legacy_auth_db_gains_the_purpose_column_unset(tmp_path, monkeypatch):
+ import sqlite3
+
+ from routes import inference as inf
+
+ db = tmp_path / "legacy" / "auth.db"
+ db.parent.mkdir()
+ monkeypatch.setattr(storage, "DB_PATH", db)
+ storage.create_initial_user(
+ username = storage.DEFAULT_ADMIN_USERNAME,
+ password = "human-password-123",
+ jwt_secret = secrets.token_urlsafe(64),
+ )
+ legacy_key, _ = storage.create_api_key(storage.DEFAULT_ADMIN_USERNAME, name = START)
+ # Rebuild api_keys as an older release left it: no purpose column at all.
+ conn = sqlite3.connect(db)
+ cols = "id, username, key_prefix, key_hash, name, created_at, last_used_at, expires_at, is_active, is_internal, account_id"
+ conn.executescript(
+ f"""CREATE TABLE old AS SELECT {cols} FROM api_keys; DROP TABLE api_keys;
+ ALTER TABLE old RENAME TO api_keys;"""
+ )
+ conn.commit()
+ conn.close()
+ storage._auth_schema_ready.clear()
+
+ assert storage.validate_api_key_account(legacy_key, touch = False)[0]["key_purpose"] is None
+ assert (
+ inf._request_may_use_saved_provider_key(
+ SimpleNamespace(headers = {"authorization": f"Bearer {legacy_key}"})
+ )
+ is False
+ )
+
+
def test_the_cli_mints_the_reserved_name():
start_py = Path(__file__).resolve().parents[3] / "unsloth_cli" / "commands" / "start.py"
assert f'{{"name": "{START}"}}' in start_py.read_text(encoding = "utf-8")
diff --git a/unsloth_cli/commands/start.py b/unsloth_cli/commands/start.py
index b2c74e70679..dd257751e9a 100644
--- a/unsloth_cli/commands/start.py
+++ b/unsloth_cli/commands/start.py
@@ -1933,11 +1933,15 @@ def _agent_api_key(
"or set UNSLOTH_API_KEY."
)
# Older releases could mint for a managed account, which cannot see the owner's model.
+ listed = _http_json(
+ "GET", f"{base}/api/auth/api-keys", token, error = "Couldn't list API keys"
+ ).get("api_keys", [])
+ # A server reporting purposes only lets stamped keys reach saved Connections: re-mint unstamped ones.
+ stamped = any("purpose" in entry for entry in listed)
owned = {
entry.get("key_prefix")
- for entry in _http_json(
- "GET", f"{base}/api/auth/api-keys", token, error = "Couldn't list API keys"
- ).get("api_keys", [])
+ for entry in listed
+ if not stamped or entry.get("purpose") == "unsloth_start"
}
for key in _cached_keys(cache, base, "minted"):
if key[len("sk-unsloth-") :][:8] in owned and _key_accepted(base, key):
diff --git a/unsloth_cli/tests/test_start.py b/unsloth_cli/tests/test_start.py
index 0d83b3a8de7..e4d5dd3bdd2 100644
--- a/unsloth_cli/tests/test_start.py
+++ b/unsloth_cli/tests/test_start.py
@@ -3248,6 +3248,34 @@ def test_connect_skips_a_minted_key_the_owner_does_not_hold(fake_studio, tmp_pat
_assert_env_set(result.output, "ANTHROPIC_AUTH_TOKEN", "sk-unsloth-feedfacefeedface")
+def test_connect_remints_a_cached_key_the_server_never_stamped(fake_studio, tmp_path, monkeypatch):
+ cache = tmp_path / "agent_api_key.json"
+ cache.write_text(json.dumps({"servers": {BASE: {"minted": ["sk-unsloth-01dc0de001dc0de0"]}}}))
+ http_json = start._http_json
+ listing = {
+ "api_keys": [
+ {"key_prefix": "01dc0de0", "purpose": None},
+ {"key_prefix": "feedface", "purpose": "unsloth_start"},
+ ]
+ }
+ monkeypatch.setattr(
+ start,
+ "_http_json",
+ lambda method, url, *a, **k: listing
+ if method == "GET" and url.endswith("/api/auth/api-keys")
+ else http_json(method, url, *a, **k),
+ )
+ result = CliRunner().invoke(start.start_app, ["claude", "--no-launch"])
+ assert result.exit_code == 0, result.output
+ _assert_env_set(result.output, "ANTHROPIC_AUTH_TOKEN", "sk-unsloth-feedfacefeedface")
+ mints = [c for c in fake_studio if c[0] == "POST" and c[1].endswith("/api/auth/api-keys")]
+ assert len(mints) == 1
+ result = CliRunner().invoke(start.start_app, ["claude", "--no-launch"])
+ _assert_env_set(result.output, "ANTHROPIC_AUTH_TOKEN", "sk-unsloth-feedfacefeedface")
+ mints = [c for c in fake_studio if c[0] == "POST" and c[1].endswith("/api/auth/api-keys")]
+ assert len(mints) == 1
+
+
def test_connect_explicit_key_remembered_for_keyless_runs(fake_studio, tmp_path):
CliRunner().invoke(
start.start_app,