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.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
import contextlib
from contextlib import contextmanager
import hashlib
import hmac
import ipaddress
import json
import logging
import os
import re
import secrets
import sqlite3
import tempfile
import threading
from datetime import datetime, timedelta, timezone
import uuid
from typing import Iterator, NamedTuple, Optional, Tuple
from storage import sqlite_gate
from utils.paths import auth_db_path, ensure_dir
logger = logging.getLogger(__name__)
DB_PATH = auth_db_path()
DEFAULT_ADMIN_USERNAME = "unsloth"
# Keep in sync with models/auth.py ChangePasswordRequest and the unsloth_cli mirror.
MIN_PASSWORD_LENGTH = 8
# Plaintext bootstrap password file, deleted on first password change.
_BOOTSTRAP_PW_PATH = DB_PATH.parent / ".bootstrap_password"
# In-process cache to avoid re-reading the file on every HTML serve.
_bootstrap_password: Optional[str] = None
def _bootstrap_file_bytes(password: str) -> bytes:
"""Exact on-disk form: the secret plus one LF. Bytes, not text: text mode writes CRLF on Windows,
and `$(cat ...)` strips the LF but leaves the CR attached to the credential."""
return (password + "\n").encode("utf-8")
def _persist_bootstrap_password(password: str) -> None:
"""Atomically write the bootstrap password 0600, LF terminated on every OS: a partial write would
destroy the only plaintext recovery credential."""
fd, tmp_name = tempfile.mkstemp(
prefix = f".{_BOOTSTRAP_PW_PATH.name}.", dir = _BOOTSTRAP_PW_PATH.parent
)
try:
with os.fdopen(fd, "wb") as f:
f.write(_bootstrap_file_bytes(password))
try:
os.chmod(tmp_name, 0o600)
except OSError:
pass
os.replace(tmp_name, _BOOTSTRAP_PW_PATH)
except BaseException:
try:
os.unlink(tmp_name)
except OSError:
pass
raise
def _normalise_bootstrap_file(raw: bytes, password: str) -> None:
"""Append-only: a rewrite could restore revoked plaintext after clear_bootstrap_password() runs."""
if raw != password.encode("utf-8"):
return
# O_BINARY: Windows text mode turns the LF back into CRLF, the bug being fixed.
fd = os.open(
_BOOTSTRAP_PW_PATH,
os.O_WRONLY | os.O_APPEND | getattr(os, "O_BINARY", 0),
)
try:
os.write(fd, b"\n")
try:
os.fchmod(fd, 0o600)
except (AttributeError, OSError):
# fchmod only reached Windows in 3.13.
pass
finally:
os.close(fd)
def _read_persisted_bootstrap_password() -> Optional[str]:
"""Read the persisted password, normalising the file if it is malformed."""
if not _BOOTSTRAP_PW_PATH.is_file():
return None
# An unreadable file must mean "no bootstrap password"; no caller handles a raise.
try:
raw = _BOOTSTRAP_PW_PATH.read_bytes()
password = raw.decode("utf-8").strip()
except (OSError, UnicodeDecodeError):
return None
if not password:
return None
# Older releases wrote no terminator; a read-only auth dir must not fail startup.
if raw != _bootstrap_file_bytes(password):
try:
_normalise_bootstrap_file(raw, password)
except OSError:
pass
return password
def generate_bootstrap_password() -> str:
"""Generate a 4-word diceware passphrase and persist it to disk. Persisted (the DB stores only the
hash) so it survives restarts; later calls return it."""
global _bootstrap_password
if _bootstrap_password is not None:
return _bootstrap_password
persisted = _read_persisted_bootstrap_password()
if persisted:
_bootstrap_password = persisted
return _bootstrap_password
import diceware
_bootstrap_password = diceware.get_passphrase(
options = diceware.handle_options(args = ["-n", "4", "-d", "", "-c"])
)
# Persist so the same passphrase survives restarts until password change.
ensure_dir(_BOOTSTRAP_PW_PATH.parent)
_persist_bootstrap_password(_bootstrap_password)
return _bootstrap_password
def get_bootstrap_password() -> Optional[str]:
return _bootstrap_password
def _load_bootstrap_password() -> Optional[str]:
"""Load an existing bootstrap password without creating one. Upgrades take this path, not
generate_bootstrap_password() (ensure_default_admin short-circuits once the admin row exists),
so it has to normalise too."""
global _bootstrap_password
_bootstrap_password = _read_persisted_bootstrap_password()
return _bootstrap_password
def clear_bootstrap_password() -> None:
"""Delete the persisted bootstrap password file (after a password change). Best-effort: the new
hash is already committed, so a locked or undeletable file must not fail the change."""
global _bootstrap_password
_bootstrap_password = None
if _BOOTSTRAP_PW_PATH.is_file():
try:
_BOOTSTRAP_PW_PATH.unlink(missing_ok = True)
except OSError as e:
# Truncate when removal fails: stale plaintext would otherwise be re-seeded if auth.db is recreated.
try:
_BOOTSTRAP_PW_PATH.write_text("", encoding = "utf-8")
cleared = True
except OSError:
cleared = False
import sys
if cleared:
message = (
f"Warning: could not delete {_BOOTSTRAP_PW_PATH.name} ({e}); "
"cleared its contents so the old bootstrap password cannot be reused."
)
else:
# Stale plaintext is still on disk and would be reused if auth.db is reset.
message = (
f"Warning: could not delete or clear {_BOOTSTRAP_PW_PATH.name} ({e}); "
"its old bootstrap password is still on disk. Remove it manually to "
"prevent reuse after a reset."
)
print(message, file = sys.stderr, flush = True)
def _hash_token(token: str) -> str:
"""Plain SHA-256 is deliberate: refresh tokens are 384-bit random, so a slow KDF buys nothing."""
return hashlib.sha256(token.encode("utf-8")).hexdigest()
class CredentialRotated(Exception):
"""A password reset revoked the credential this request authenticated with."""
def credential_generation(jwt_secret: str) -> str:
"""Credential version a refresh token was issued under; a password change rotates jwt_secret, so
the old stamp is rejected even if inserted after the revoking DELETE."""
return hashlib.sha256(jwt_secret.encode("utf-8")).hexdigest()
# Downgrade fence: a build without account support 401s a managed login.
_FENCE_PREFIX = "account:"
_FENCED_HASH_SQL = "IN (?, ?)"
_LEGACY_PASSWORD_HASH_SENTINEL = "managed-account"
_SECRET_SQL = "COALESCE(account_jwt_secret, jwt_secret)"
_PASSWORD_HASH_SQL = "COALESCE(account_password_hash, password_hash)"
_PASSWORD_SALT_SQL = "COALESCE(account_password_salt, password_salt)"
def _is_owner_name(username: str) -> bool:
return username == DEFAULT_ADMIN_USERNAME
def _fenced_hash(digest: str, username: str) -> str:
return digest if _is_owner_name(username) else _FENCE_PREFIX + digest
def _hash_candidates(digest: str) -> tuple[str, str]:
return digest, _FENCE_PREFIX + digest
def _legacy_dummies() -> tuple[str, str, str]:
return secrets.token_hex(16), _LEGACY_PASSWORD_HASH_SENTINEL, secrets.token_urlsafe(64)
def _current_secret(conn: sqlite3.Connection, username: str) -> Optional[str]:
row = conn.execute(
f"SELECT {_SECRET_SQL} AS jwt_secret FROM auth_user WHERE username = ?", (username,)
).fetchone()
return row["jwt_secret"] if row else None
def _current_generation(conn: sqlite3.Connection, username: str) -> Optional[str]:
secret = _current_secret(conn, username)
return credential_generation(secret) if secret is not None else None
@contextmanager
def credential_generation_guard(username: str, expect_gen: Optional[str]) -> Iterator[None]:
"""Hold the auth write lock while a credential-derived write commits elsewhere."""
conn = get_connection()
try:
if expect_gen is not None:
conn.execute("BEGIN IMMEDIATE")
if _current_generation(conn, username) != expect_gen:
raise CredentialRotated(
"The credential this request authenticated with was revoked."
)
yield
conn.commit()
except Exception:
conn.rollback()
raise
finally:
conn.close()
_auth_schema_ready: set[tuple[str, int, int, int]] = set()
_BUSY_TIMEOUT_MS = 5000
def get_connection(*, check_same_thread: bool = True) -> sqlite3.Connection:
ensure_dir(DB_PATH.parent)
conn = sqlite_gate.connect(DB_PATH, check_same_thread = check_same_thread)
# sqlite3.connect would create the DB 0644 under a 022 umask, exposing identity secrets and password hashes.
for _path, _mode in ((DB_PATH.parent, 0o700), (DB_PATH, 0o600)):
try:
os.chmod(_path, _mode)
except OSError:
pass
conn.row_factory = sqlite3.Row
# busy_timeout before journal_mode=WAL, else the mode switch raises SQLITE_BUSY.
try:
conn.execute(f"PRAGMA busy_timeout={int(_BUSY_TIMEOUT_MS)}")
conn.execute("PRAGMA journal_mode=WAL")
except sqlite3.Error:
pass
# Per connection, so before the schema-cache return below.
sqlite_gate.apply_wal_synchronous(conn)
file_stat = DB_PATH.stat()
schema_key = (
str(DB_PATH),
file_stat.st_dev,
file_stat.st_ino,
conn.execute("PRAGMA schema_version").fetchone()[0],
)
if schema_key in _auth_schema_ready:
return conn
conn.execute(
"""
CREATE TABLE IF NOT EXISTS auth_user (
id INTEGER PRIMARY KEY,
username TEXT UNIQUE NOT NULL,
password_salt TEXT NOT NULL,
password_hash TEXT NOT NULL,
jwt_secret TEXT NOT NULL,
must_change_password INTEGER NOT NULL DEFAULT 0
);
"""
)
conn.execute(
"""
CREATE TABLE IF NOT EXISTS refresh_tokens (
id INTEGER PRIMARY KEY,
token_hash TEXT NOT NULL,
username TEXT NOT NULL,
expires_at TEXT NOT NULL,
is_desktop INTEGER NOT NULL DEFAULT 0,
secret_gen TEXT
);
"""
)
conn.execute(
"""
CREATE TABLE IF NOT EXISTS api_keys (
id INTEGER PRIMARY KEY AUTOINCREMENT,
username TEXT NOT NULL,
key_prefix TEXT NOT NULL,
key_hash TEXT NOT NULL UNIQUE,
name TEXT NOT NULL DEFAULT '',
created_at TEXT NOT NULL,
last_used_at TEXT,
expires_at TEXT,
is_active INTEGER NOT NULL DEFAULT 1,
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 (
key TEXT PRIMARY KEY,
value TEXT NOT NULL
);
"""
)
columns = {row["name"] for row in conn.execute("PRAGMA table_info(auth_user)")}
if "must_change_password" not in columns:
conn.execute(
"ALTER TABLE auth_user ADD COLUMN must_change_password INTEGER NOT NULL DEFAULT 0"
)
_ensure_account_columns(conn, columns)
_ensure_account_api_keys(conn, api_key_columns)
refresh_columns = {row["name"] for row in conn.execute("PRAGMA table_info(refresh_tokens)")}
if "is_desktop" not in refresh_columns:
conn.execute("ALTER TABLE refresh_tokens ADD COLUMN is_desktop INTEGER NOT NULL DEFAULT 0")
if "secret_gen" not in refresh_columns:
conn.execute("ALTER TABLE refresh_tokens ADD COLUMN secret_gen TEXT")
conn.commit()
_auth_schema_ready.add(
(
*schema_key[:3],
conn.execute("PRAGMA schema_version").fetchone()[0],
)
)
return conn
# No lock needed: INSERT OR IGNORE is atomic and concurrent populations converge.
# ── API-key PBKDF2 salt ────────────────────────────────────────────────
_api_key_pbkdf2_salt_cache: Optional[bytes] = None
_ACCOUNT_COLUMNS = (
("account_id", "TEXT"),
("role", "TEXT NOT NULL DEFAULT 'user'"),
("is_active", "INTEGER NOT NULL DEFAULT 1"),
("created_at", "TEXT"),
("setup_code_hash", "TEXT"),
("setup_code_expires_at", "TEXT"),
("account_password_salt", "TEXT"),
("account_password_hash", "TEXT"),
("account_jwt_secret", "TEXT"),
# JSON list of repo ids / ``org/*`` patterns; NULL = every model (#11650).
("model_allowlist", "TEXT"),
# Owner's extra sign-in name; NULL = "unsloth" only.
("login_alias", "TEXT"),
)
_owner_id_repaired: set[str] = set()
# Without a keeper each close is the last WAL participant and checkpoints under sqlite_gate's
# process-wide lock. Lifespan-only, never lazy: tests swap and unlink auth.db.
_wal_keeper_lock = threading.Lock()
_wal_keeper: Optional[tuple[str, sqlite3.Connection]] = None
def _close_keeper(conn: sqlite3.Connection) -> None:
try:
conn.close()
except Exception as exc:
logger.warning("Could not close the auth.db WAL keeper: %s", exc)
def open_wal_keeper() -> bool:
"""Hold auth.db's WAL open for the server's lifetime, replacing any earlier keeper."""
global _wal_keeper
with _wal_keeper_lock:
if _wal_keeper is not None:
_close_keeper(_wal_keeper[1])
_wal_keeper = None
conn = get_connection(check_same_thread = False)
try:
mode = conn.execute("PRAGMA journal_mode").fetchone()[0]
except (sqlite3.Error, TypeError, IndexError) as exc:
_close_keeper(conn)
logger.warning("Could not read auth.db journal mode: %s", exc)
return False
if not isinstance(mode, str) or mode.lower() != "wal":
_close_keeper(conn)
logger.info("auth.db is in %s mode, not WAL; WAL keeper not engaged.", mode)
return False
_wal_keeper = (str(DB_PATH.resolve()), conn)
return True
def close_wal_keeper() -> None:
global _wal_keeper
with _wal_keeper_lock:
if _wal_keeper is not None:
_close_keeper(_wal_keeper[1])
_wal_keeper = None
def _repair_owner_account_id(conn: sqlite3.Connection) -> None:
db_key = str(DB_PATH)
if db_key in _owner_id_repaired:
return
from utils.account_context import OWNER_ACCOUNT_ID, ROLE_OWNER
repaired = conn.execute(
"UPDATE auth_user SET account_id = ?, role = ?, created_at = COALESCE(created_at, ?) "
"WHERE username = ? AND account_id IS NULL",
(
OWNER_ACCOUNT_ID,
ROLE_OWNER,
datetime.now(timezone.utc).isoformat(),
DEFAULT_ADMIN_USERNAME,
),
).rowcount
if repaired:
conn.execute(
"CREATE UNIQUE INDEX IF NOT EXISTS auth_user_account_id ON auth_user(account_id)"
)
conn.commit()
_owner_id_repaired.add(db_key)
def _ensure_account_columns(conn: sqlite3.Connection, existing: set) -> None:
if all(name in existing for name, _decl in _ACCOUNT_COLUMNS):
_repair_owner_account_id(conn)
return
# Re-read under the write lock: a losing concurrent ALTER is not an error.
conn.execute("BEGIN IMMEDIATE")
try:
existing = {row[1] for row in conn.execute("PRAGMA table_info(auth_user)")}
added = False
fence_added = False
for name, decl in _ACCOUNT_COLUMNS:
if name in existing:
continue
try:
conn.execute(f"ALTER TABLE auth_user ADD COLUMN {name} {decl}")
except sqlite3.OperationalError as exc:
if "duplicate column" not in str(exc).lower():
raise
continue
added = True
fence_added = fence_added or name == "account_jwt_secret"
if added:
_backfill_account_columns(conn, fence_added)
conn.commit()
except BaseException:
conn.rollback()
raise
_ACCOUNT_API_KEY_COLUMNS = "username, key_prefix, key_hash, name, created_at, expires_at, is_active, is_internal, account_id"
_account_keys_synced: set[str] = set()
def _ensure_account_api_keys(conn: sqlite3.Connection, existing: set) -> None:
"""Pin managed API keys to the immutable ``account_id`` (a namesake inherits none) and mirror
them into ``account_api_keys``. Idempotent."""
db_key = str(DB_PATH)
if db_key in _account_keys_synced and "account_id" in existing:
return
if "account_id" not in existing:
try:
conn.execute("ALTER TABLE api_keys ADD COLUMN account_id TEXT")
except sqlite3.OperationalError as exc:
if "duplicate column" not in str(exc).lower():
raise
conn.execute(
"""UPDATE api_keys SET account_id = (
SELECT account_id FROM auth_user
WHERE auth_user.username = api_keys.username AND auth_user.role != 'owner'
) WHERE account_id IS NULL"""
)
conn.execute(
"""
CREATE TABLE IF NOT EXISTS account_api_keys (
id INTEGER PRIMARY KEY AUTOINCREMENT,
username TEXT NOT NULL,
key_prefix TEXT NOT NULL,
key_hash TEXT NOT NULL UNIQUE,
name TEXT NOT NULL DEFAULT '',
created_at TEXT NOT NULL,
expires_at TEXT,
is_active INTEGER NOT NULL DEFAULT 1,
is_internal INTEGER NOT NULL DEFAULT 0,
account_id TEXT NOT NULL
);
"""
)
conn.execute(
f"""INSERT INTO account_api_keys ({_ACCOUNT_API_KEY_COLUMNS})
SELECT {_ACCOUNT_API_KEY_COLUMNS} FROM api_keys k
WHERE k.account_id IS NOT NULL
AND NOT EXISTS (SELECT 1 FROM account_api_keys b WHERE b.key_hash = k.key_hash)"""
)
conn.execute(
f"""INSERT INTO api_keys ({_ACCOUNT_API_KEY_COLUMNS})
SELECT {_ACCOUNT_API_KEY_COLUMNS} FROM account_api_keys b
WHERE NOT EXISTS (SELECT 1 FROM api_keys k WHERE k.key_hash = b.key_hash)
AND EXISTS (SELECT 1 FROM auth_user u WHERE u.account_id = b.account_id)"""
)
conn.commit()
_account_keys_synced.add(db_key)
def _backfill_account_columns(conn: sqlite3.Connection, fence_added: bool) -> None:
from utils.account_context import OWNER_ACCOUNT_ID, ROLE_OWNER, ROLE_USER
import uuid
now = datetime.now(timezone.utc).isoformat()
for row_id, username, account_id in conn.execute(
"SELECT id, username, account_id FROM auth_user"
).fetchall():
if account_id:
continue
if username == DEFAULT_ADMIN_USERNAME:
account_id, role = OWNER_ACCOUNT_ID, ROLE_OWNER
else:
account_id, role = uuid.uuid4().hex, ROLE_USER
conn.execute(
"UPDATE auth_user SET account_id = ?, role = ?, created_at = COALESCE(created_at, ?) WHERE id = ?",
(account_id, role, now, row_id),
)
conn.execute("CREATE UNIQUE INDEX IF NOT EXISTS auth_user_account_id ON auth_user(account_id)")
if fence_added:
_fence_managed_credentials(conn)
def _fence_managed_credentials(conn: sqlite3.Connection) -> None:
# Positional reads: the caller's connection may lack a row factory.
rows = conn.execute(
"SELECT id, password_salt, password_hash, jwt_secret FROM auth_user "
"WHERE role = 'user' AND account_jwt_secret IS NULL"
).fetchall()
for row_id, real_salt, real_hash, real_secret in rows:
salt, pwd_hash, secret = _legacy_dummies()
conn.execute(
"""UPDATE auth_user
SET account_password_salt = ?, account_password_hash = ?, account_jwt_secret = ?,
password_salt = ?, password_hash = ?, jwt_secret = ?
WHERE id = ?""",
(real_salt, real_hash, real_secret, salt, pwd_hash, secret, row_id),
)
managed = "SELECT username FROM auth_user WHERE role = 'user'"
conn.execute(
f"UPDATE api_keys SET key_hash = ? || key_hash WHERE username IN ({managed}) AND key_hash NOT LIKE ?",
(_FENCE_PREFIX, _FENCE_PREFIX + "%"),
)
conn.execute(
f"UPDATE refresh_tokens SET token_hash = ? || token_hash WHERE username IN ({managed}) AND token_hash NOT LIKE ?",
(_FENCE_PREFIX, _FENCE_PREFIX + "%"),
)
def get_user_record(username: str) -> Optional[dict]:
conn = get_connection()
try:
row = conn.execute(
f"""
SELECT username, {_PASSWORD_SALT_SQL} AS password_salt,
{_PASSWORD_HASH_SQL} AS password_hash, {_SECRET_SQL} AS jwt_secret,
must_change_password, account_id, role, is_active
FROM auth_user WHERE username = ?
""",
(username,),
).fetchone()
return dict(row) if row else None
finally:
conn.close()
def get_account(username: str):
from utils.account_context import AccountContext
record = get_user_record(username)
if record is None:
return None
return AccountContext(record["account_id"], record["username"], record["role"])
def get_account_by_id(account_id: str):
from utils.account_context import AccountContext
conn = get_connection()
try:
row = conn.execute(
"SELECT account_id, username, role, is_active FROM auth_user WHERE account_id = ?",
(account_id,),
).fetchone()
finally:
conn.close()
if row is None or not row["is_active"]:
return None
return AccountContext(row["account_id"], row["username"], row["role"])
def count_active_accounts() -> int:
return account_counts()[0]
def account_counts() -> tuple[int, int]:
"""``(active, managed-of-any-state)``; the second counts deactivated accounts too."""
conn = get_connection()
try:
row = conn.execute(
"""
SELECT COALESCE(SUM(CASE WHEN is_active = 1 THEN 1 ELSE 0 END), 0) AS active,
COALESCE(SUM(CASE WHEN role IS NOT NULL AND role != 'owner' THEN 1 ELSE 0 END), 0) AS managed
FROM auth_user
"""
).fetchone()
return int(row["active"]), int(row["managed"])
finally:
conn.close()
def validate_account_username(username: str) -> str:
username = username.casefold()
if re.fullmatch(r"[a-z0-9_-]{3,32}", username) is None:
raise ValueError("Username must contain 3 to 32 letters, digits, underscores or hyphens")
if username in {"unsloth", "owner", "admin", "root", "system"}:
raise ValueError("This username is reserved")
return username
MAX_MODEL_ALLOWLIST_ENTRIES = 500
# ``org/name``, ``org/*``, or a legacy top-level id such as ``gpt2``.
_MODEL_ALLOWLIST_ENTRY = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]{0,95}(?:/[A-Za-z0-9._*-]{1,96})?")
_HUB_URL_PREFIX = re.compile(r"^(?:https?://)?(?:www\.)?(?:hf\.co|huggingface\.co)/", re.IGNORECASE)
def normalize_model_allowlist(entries) -> Optional[list[str]]:
"""Repo ids or ``org/*`` patterns, lowercased and deduplicated; empty means unrestricted."""
if entries is None:
return None
normalized: list[str] = []
for entry in entries:
if not isinstance(entry, str):
raise ValueError("Model access entries must be strings")
entry = _HUB_URL_PREFIX.sub("", entry.strip()).split(":", 1)[0].strip("/")
if not entry:
continue
if _MODEL_ALLOWLIST_ENTRY.fullmatch(entry) is None:
raise ValueError(
f"{entry!r} is not a Hugging Face model id such as unsloth/Qwen3-4B-GGUF or unsloth/*"
)
entry = entry.lower()
if entry not in normalized:
normalized.append(entry)
if len(normalized) > MAX_MODEL_ALLOWLIST_ENTRIES:
raise ValueError(f"At most {MAX_MODEL_ALLOWLIST_ENTRIES} models can be listed")
return normalized or None
def _decode_model_allowlist(raw) -> Optional[list[str]]:
if raw is None:
return None
try:
value = json.loads(raw)
except (TypeError, ValueError):
# A corrupt row must not silently grant every model.
return []
if not isinstance(value, list):
return []
return [entry for entry in value if isinstance(entry, str)]
def _public_account(row) -> dict:
return {
"account_id": row["account_id"],
"username": row["username"],
"role": row["role"],
"is_active": bool(row["is_active"]),
"created_at": row["created_at"],
"setup_code_pending": bool(row["setup_code_hash"]),
"model_allowlist": (
_decode_model_allowlist(row["model_allowlist"])
if "model_allowlist" in row.keys()
else None
),
"login_alias": row["login_alias"] if "login_alias" in row.keys() else None,
}
def list_accounts() -> list[dict]:
conn = get_connection()
try:
return [
_public_account(row)
for row in conn.execute("SELECT * FROM auth_user ORDER BY created_at, account_id")
]
finally:
conn.close()
def _managed_account(conn: sqlite3.Connection, account_id: str):
row = conn.execute("SELECT * FROM auth_user WHERE account_id = ?", (account_id,)).fetchone()
if row is None:
raise LookupError("Account not found")
if row["role"] == "owner" or account_id == "owner":
raise ValueError("The installation owner cannot be modified here")
return row
def _revoke_account_credentials(conn: sqlite3.Connection, row) -> None:
# Legacy tables key on username; resolve it under the same write lock.
conn.execute("DELETE FROM refresh_tokens WHERE username = ?", (row["username"],))
conn.execute("DELETE FROM api_keys WHERE username = ?", (row["username"],))
conn.execute("DELETE FROM account_api_keys WHERE account_id = ?", (row["account_id"],))
conn.execute(
"UPDATE auth_user SET account_jwt_secret = ? WHERE account_id = ?",
(secrets.token_urlsafe(64), row["account_id"]),
)
def issue_account_setup_code(
*, username: Optional[str] = None, account_id: Optional[str] = None
) -> dict:
from auth.hashing import hash_password
from auth.policy import account_mutation
if (username is None) == (account_id is None):
raise ValueError("Specify either a username or an account id")
if username is not None:
username = validate_account_username(username)
code = secrets.token_urlsafe(32)
salt, pwd_hash = hash_password(code)
# Before the transaction: a first-run salt creation opens its own connection.
code_hash = _hash_setup_code(code)
now = datetime.now(timezone.utc)
expires_at = (now + timedelta(minutes = 60)).isoformat()
with account_mutation():
conn = get_connection()
try:
with conn:
conn.execute("BEGIN IMMEDIATE")
if username is not None:
owner = conn.execute(
"SELECT must_change_password FROM auth_user WHERE role = 'owner'"
).fetchone()
if owner is not None and owner["must_change_password"]:
raise ValueError("Set the owner's password before adding an account.")
if _login_alias_taken(conn, username):
raise sqlite3.IntegrityError("Username is unavailable")
account_id = uuid.uuid4().hex
legacy_salt, legacy_hash, legacy_secret = _legacy_dummies()
conn.execute(
"""INSERT INTO auth_user
(username, account_id, role, is_active, created_at, password_salt,
password_hash, jwt_secret, account_password_salt, account_password_hash,
account_jwt_secret, must_change_password, setup_code_hash, setup_code_expires_at)
VALUES (?, ?, 'user', 1, ?, ?, ?, ?, ?, ?, ?, 1, ?, ?)""",
(
username,
account_id,
now.isoformat(),
legacy_salt,
legacy_hash,
legacy_secret,
salt,
pwd_hash,
secrets.token_urlsafe(64),
code_hash,
expires_at,
),
)
else:
row = _managed_account(conn, account_id)
_revoke_account_credentials(conn, row)
conn.execute(
"""UPDATE auth_user SET account_password_salt = ?, account_password_hash = ?,
must_change_password = 1, setup_code_hash = ?, setup_code_expires_at = ?
WHERE account_id = ?""",
(salt, pwd_hash, code_hash, expires_at, account_id),
)
account = _public_account(_managed_account(conn, account_id))
finally:
conn.close()
return {"account": account, "setup_code": code, "setup_code_expires_at": expires_at}
def _login_alias_taken(conn: sqlite3.Connection, name: str) -> bool:
return (
conn.execute("SELECT 1 FROM auth_user WHERE login_alias = ?", (name,)).fetchone()
is not None
)
def resolve_login_username(username: str) -> str:
if username == DEFAULT_ADMIN_USERNAME:
return username
conn = get_connection()
try:
# A real username always wins, should one ever collide with the alias.
row = conn.execute(
"SELECT username FROM auth_user WHERE login_alias = ? AND role = 'owner' "
"AND NOT EXISTS (SELECT 1 FROM auth_user WHERE username = ?)",
(username, username),
).fetchone()
finally:
conn.close()
return row["username"] if row else username
def set_owner_login_alias(alias: Optional[str]) -> Optional[str]:
"""None, blank or "unsloth" clears it."""
alias = (alias or "").strip()
alias = (
None
if alias.casefold() in ("", DEFAULT_ADMIN_USERNAME)
else validate_account_username(alias)
)
conn = get_connection()
try:
with conn:
conn.execute("BEGIN IMMEDIATE")
# Same write lock as account creation, so neither can take a name the other just took.
if (
alias is not None
and conn.execute("SELECT 1 FROM auth_user WHERE username = ?", (alias,)).fetchone()
):
raise sqlite3.IntegrityError("Username is unavailable")
conn.execute(
"UPDATE auth_user SET login_alias = ? WHERE username = ?",
(alias, DEFAULT_ADMIN_USERNAME),
)
finally:
conn.close()
return alias
def authenticate_account_login(
username: str, password: str
) -> Optional[Tuple[str, str, str, bool]]:
"""Managed login. A setup code is consumed once; must_change_password with no pending code
admits only the issued session's password change."""
from auth.hashing import equalize_login_work, verify_password
def miss():
# A miss without a hash to check costs what a wrong password costs.
equalize_login_work(password)
return None
conn = get_connection()
try:
row = conn.execute(
f"""SELECT account_id, is_active, must_change_password, setup_code_hash,
{_PASSWORD_SALT_SQL} AS password_salt, {_PASSWORD_HASH_SQL} AS password_hash,
{_SECRET_SQL} AS jwt_secret
FROM auth_user WHERE username = ?""",
(username,),
).fetchone()
if row is None or not row["is_active"]:
return miss()
if row["must_change_password"]:
# The setup-code hash is the PBKDF2 round a miss would otherwise spend.
if not row["setup_code_hash"] or not hmac.compare_digest(
row["setup_code_hash"], _hash_setup_code(password)
):
return None
# Compare-and-swap on expiry, activity and generation: no code is spent twice.
with conn:
cursor = conn.execute(
f"""UPDATE auth_user SET setup_code_hash = NULL, setup_code_expires_at = NULL
WHERE account_id = ? AND setup_code_hash = ? AND {_SECRET_SQL} = ?
AND is_active = 1 AND setup_code_expires_at > ?""",
(
row["account_id"],
row["setup_code_hash"],
row["jwt_secret"],
datetime.now(timezone.utc).isoformat(),
),
)
if cursor.rowcount != 1:
return None
elif not verify_password(password, row["password_salt"], row["password_hash"]):
return None
return (
row["password_salt"],
row["password_hash"],
row["jwt_secret"],
bool(row["must_change_password"]),
)
finally:
conn.close()
def update_account_password(
username: str, new_password: str, *, expect_password_hash: str, expect_secret: str
) -> Optional[str]:
from auth.hashing import hash_password
salt, pwd_hash = hash_password(new_password)
secret = secrets.token_urlsafe(64)
conn = get_connection()
try:
with conn:
cursor = conn.execute(
f"""UPDATE auth_user SET account_password_salt = ?, account_password_hash = ?,
account_jwt_secret = ?, must_change_password = 0,
setup_code_hash = NULL, setup_code_expires_at = NULL
WHERE username = ? AND role = 'user' AND is_active = 1
AND {_PASSWORD_HASH_SQL} = ? AND {_SECRET_SQL} = ?""",
(salt, pwd_hash, secret, username, expect_password_hash, expect_secret),
)
if cursor.rowcount != 1:
return None
conn.execute("DELETE FROM refresh_tokens WHERE username = ?", (username,))
return secret
finally:
conn.close()
def set_account_active(account_id: str, is_active: bool) -> dict:
from auth.policy import account_mutation
with account_mutation():
conn = get_connection()
try:
with conn:
conn.execute("BEGIN IMMEDIATE")
row = _managed_account(conn, account_id)
if not is_active:
_revoke_account_credentials(conn, row)
conn.execute(
"UPDATE auth_user SET is_active = ? WHERE account_id = ?",
(int(is_active), account_id),
)
result = _public_account(_managed_account(conn, account_id))
finally:
conn.close()
return result
def set_account_model_allowlist(account_id: str, allowlist: Optional[list[str]]) -> dict:
from auth.policy import account_mutation
allowlist = normalize_model_allowlist(allowlist)
with account_mutation():
conn = get_connection()
try:
with conn:
conn.execute("BEGIN IMMEDIATE")
_managed_account(conn, account_id)
conn.execute(
"UPDATE auth_user SET model_allowlist = ? WHERE account_id = ?",
(None if allowlist is None else json.dumps(allowlist), account_id),
)
result = _public_account(_managed_account(conn, account_id))
finally:
conn.close()
return result
def rename_account(account_id: str, username: str) -> dict:
"""Data keys on account_id, so nothing moves; sessions are revoked, API keys follow the account."""
from auth.policy import account_mutation
username = validate_account_username(username)
with account_mutation():
conn = get_connection()
try:
with conn:
conn.execute("BEGIN IMMEDIATE")
row = _managed_account(conn, account_id)
old = row["username"]
if old != username:
if _login_alias_taken(conn, username):
raise sqlite3.IntegrityError("Username is unavailable")
conn.execute(
"UPDATE auth_user SET username = ?, account_jwt_secret = ? WHERE account_id = ?",
(username, secrets.token_urlsafe(64), account_id),
)
conn.execute("DELETE FROM refresh_tokens WHERE username = ?", (old,))
conn.execute(
"UPDATE api_keys SET username = ? WHERE username = ? AND account_id = ?",
(username, old, account_id),
)
conn.execute(
"UPDATE account_api_keys SET username = ? WHERE account_id = ?",
(username, account_id),
)
result = _public_account(_managed_account(conn, account_id))
finally:
conn.close()
return result
def account_model_allowlist(account_id: str) -> Optional[tuple[str, ...]]:
"""``None`` = every model. The owner is never restricted."""
conn = get_connection()
try:
row = conn.execute(
"SELECT role, model_allowlist FROM auth_user WHERE account_id = ?", (account_id,)
).fetchone()
finally:
conn.close()
# A deleted account is fenced by credential revocation, not here.
if row is None or row["role"] == "owner":
return None
allowlist = _decode_model_allowlist(row["model_allowlist"])
return None if allowlist is None else tuple(allowlist)
def delete_account(account_id: str, retire) -> None:
"""Revoke, retire files, then drop the identity under a write lock. ``retire()`` must not write
auth.db under that lock; a failed retire leaves the account disabled for a retry."""
from auth.policy import account_mutation
from utils.account_context import AccountContext
set_account_active(account_id, False)
with account_mutation():
conn = get_connection()
restore_roots = None
try:
with conn:
conn.execute("BEGIN IMMEDIATE")
row = _managed_account(conn, account_id)
_revoke_account_credentials(conn, row)
restore_roots = retire(
AccountContext(row["account_id"], row["username"], row["role"])
)
conn.execute("DELETE FROM auth_user WHERE account_id = ?", (account_id,))
except Exception:
# Restore the roots too; a failed restore is the error to report.
try:
if restore_roots is not None:
restore_roots()
finally:
# An owner may reactivate between revocation and this lock; stay disabled anyway.
with contextlib.suppress(sqlite3.Error):
set_account_active(account_id, False)
raise
finally:
conn.close()
def _get_or_create_api_key_pbkdf2_salt() -> bytes:
"""Return the persistent API-key PBKDF2 salt, generating it once if missing. Hex-encoded 32-byte
random value in ``app_secrets``, regenerated only when the row is missing."""
global _api_key_pbkdf2_salt_cache
if _api_key_pbkdf2_salt_cache is not None:
return _api_key_pbkdf2_salt_cache
conn = get_connection()
try:
cur = conn.execute(
"SELECT value FROM app_secrets WHERE key = ?",
("api_key_pbkdf2_salt",),
)
row = cur.fetchone()
if row is None:
new_value = secrets.token_hex(32)
conn.execute(
"INSERT OR IGNORE INTO app_secrets (key, value) VALUES (?, ?)",
("api_key_pbkdf2_salt", new_value),
)
conn.commit()
cur = conn.execute(
"SELECT value FROM app_secrets WHERE key = ?",
("api_key_pbkdf2_salt",),
)
row = cur.fetchone()
salt = bytes.fromhex(row["value"])
finally:
conn.close()
_api_key_pbkdf2_salt_cache = salt
return salt
# Identity-challenge secret lives in auth.db so a port squatter cannot forge a proof; separate from the JWT secret.
_IDENTITY_SECRET_DB_KEY = "studio_identity_secret"
_identity_secret_cache: Optional[bytes] = None
def get_or_create_identity_secret() -> bytes:
"""Return the identity secret (hex 32-byte row in app_secrets), creating it once."""
global _identity_secret_cache
if _identity_secret_cache is not None:
return _identity_secret_cache
conn = get_connection()
try:
row = conn.execute(
"SELECT value FROM app_secrets WHERE key = ?",
(_IDENTITY_SECRET_DB_KEY,),
).fetchone()
if row is None:
conn.execute(
"INSERT OR IGNORE INTO app_secrets (key, value) VALUES (?, ?)",
(_IDENTITY_SECRET_DB_KEY, secrets.token_hex(32)),
)
conn.commit()
row = conn.execute(
"SELECT value FROM app_secrets WHERE key = ?",
(_IDENTITY_SECRET_DB_KEY,),
).fetchone()
secret = bytes.fromhex(row["value"])
finally:
conn.close()
_identity_secret_cache = secret
return secret
# In auth.db so copying studio.db alone does not expose tokens; survives password resets.
_CREDENTIAL_ENCRYPTION_KEY_DB_KEY = "credential_encryption_key_v1"
_credential_encryption_key_cache: Optional[bytes] = None
def get_or_create_credential_encryption_key() -> bytes:
"""Return the install-local credential encryption key, creating it once."""
global _credential_encryption_key_cache
if _credential_encryption_key_cache is not None:
return _credential_encryption_key_cache
conn = get_connection()
try:
row = conn.execute(
"SELECT value FROM app_secrets WHERE key = ?",
(_CREDENTIAL_ENCRYPTION_KEY_DB_KEY,),
).fetchone()
if row is None:
conn.execute(
"INSERT OR IGNORE INTO app_secrets (key, value) VALUES (?, ?)",
(_CREDENTIAL_ENCRYPTION_KEY_DB_KEY, secrets.token_hex(32)),
)
conn.commit()
row = conn.execute(
"SELECT value FROM app_secrets WHERE key = ?",
(_CREDENTIAL_ENCRYPTION_KEY_DB_KEY,),
).fetchone()
secret = bytes.fromhex(row["value"])
if len(secret) != 32:
raise ValueError("Invalid credential encryption key")
finally:
conn.close()
_credential_encryption_key_cache = secret
return secret
def compute_identity_proof(nonce: bytes, host: str, port: int) -> str:
"""HMAC bound to the connection's host and port, so a proof relayed from another endpoint fails."""
try:
host = ipaddress.ip_address(host).compressed
except ValueError:
host = (host or "").lower()
msg = b"|".join([nonce, host.encode(), str(int(port)).encode()])
return hmac.new(get_or_create_identity_secret(), msg, hashlib.sha256).hexdigest()
# Dedicated secret so rotating it revokes every shared preview link without touching logins.
_PREVIEW_LINK_SECRET_DB_KEY = "preview_link_secret"
_preview_link_secret_cache: Optional[bytes] = None
def get_or_create_preview_link_secret() -> bytes:
"""Return the preview-link signing secret (hex 32-byte row in app_secrets), creating it once."""
global _preview_link_secret_cache
if _preview_link_secret_cache is not None:
return _preview_link_secret_cache
conn = get_connection()
try:
row = conn.execute(
"SELECT value FROM app_secrets WHERE key = ?",
(_PREVIEW_LINK_SECRET_DB_KEY,),
).fetchone()
if row is None:
conn.execute(
"INSERT OR IGNORE INTO app_secrets (key, value) VALUES (?, ?)",
(_PREVIEW_LINK_SECRET_DB_KEY, secrets.token_hex(32)),
)
conn.commit()
row = conn.execute(
"SELECT value FROM app_secrets WHERE key = ?",
(_PREVIEW_LINK_SECRET_DB_KEY,),
).fetchone()
secret = bytes.fromhex(row["value"])
finally:
conn.close()
_preview_link_secret_cache = secret
return secret
def rotate_preview_link_secret() -> bytes:
"""Rotate the preview-link secret, immediately revoking every outstanding ``/p`` share link."""
global _preview_link_secret_cache
new_secret_hex = secrets.token_hex(32)
conn = get_connection()
try:
conn.execute(
"INSERT OR REPLACE INTO app_secrets (key, value) VALUES (?, ?)",
(_PREVIEW_LINK_SECRET_DB_KEY, new_secret_hex),
)
conn.commit()
finally:
conn.close()
secret = bytes.fromhex(new_secret_hex)
_preview_link_secret_cache = secret
return secret
_API_KEY_PBKDF2_ITERATIONS = 100_000
DESKTOP_SECRET_PREFIX = "desktop-"
_DESKTOP_SECRET_HASH_KEY = "desktop_secret_hash"
_DESKTOP_SECRET_CREATED_AT_KEY = "desktop_secret_created_at"
# token_urlsafe(48) is exactly 64 chars. Keep in sync with unsloth_cli/commands/studio.py
# and the desktop- alternation in core/inference/tool_loop_controller.py.
_DESKTOP_SECRET_BODY = re.compile(r"\A[A-Za-z0-9_-]{64}\Z")
def desktop_secret_is_well_formed(raw_secret: str) -> bool:
"""Syntax only and KDF-free, so the desktop shell's invalid-secret probe costs no rate-limit budget."""
if not isinstance(raw_secret, str) or not raw_secret.startswith(DESKTOP_SECRET_PREFIX):
return False
return _DESKTOP_SECRET_BODY.match(raw_secret[len(DESKTOP_SECRET_PREFIX) :]) is not None
def _pbkdf2_api_key(raw_key: str) -> str:
"""API-key only; salt in ``app_secrets`` means dumping ``api_keys`` alone cannot derive hashes."""
salt = _get_or_create_api_key_pbkdf2_salt()
dk = hashlib.pbkdf2_hmac(
"sha256",
raw_key.encode("utf-8"),
salt,
_API_KEY_PBKDF2_ITERATIONS,
)
return dk.hex()
def _pbkdf2_desktop_secret(raw_secret: str) -> str:
return _pbkdf2_api_key(raw_secret)
def _hash_setup_code(code: str) -> str:
"""A setup code is typed where a password goes, so it is stored like an API key."""
return _pbkdf2_api_key(code)
# Keyed by a salted HMAC; revocation/expiry are still enforced by the SQLite read.
_api_key_hash_cache: dict[str, str] = {}
# Whether each memoized key was minted internally; set once, since minting decides it.
_api_key_internal_cache: dict[str, bool] = {}
_API_KEY_HASH_CACHE_MAX = 4096
_api_key_hash_cache_lock = threading.Lock()
def _api_key_cache_id(raw_key: str) -> str:
"""Cache id for a raw key: salted HMAC-SHA256 (not the key itself)."""
return hmac.new(
_get_or_create_api_key_pbkdf2_salt(), raw_key.encode("utf-8"), hashlib.sha256
).hexdigest()
def _reset_api_key_hash_cache() -> None:
with _api_key_hash_cache_lock:
_api_key_hash_cache.clear()
_api_key_internal_cache.clear()
def is_initialized() -> bool:
conn = get_connection()
cur = conn.execute("SELECT COUNT(*) AS c FROM auth_user")
row = cur.fetchone()
conn.close()
return bool(row["c"])
def create_initial_user(
username: str,
password: str,
jwt_secret: str,
*,
must_change_password: bool = False,
) -> None:
"""Creates the first admin; raises sqlite3.IntegrityError if the username exists."""
from .hashing import hash_password
from utils.account_context import OWNER_ACCOUNT_ID, ROLE_OWNER, ROLE_USER
import uuid
salt, pwd_hash = hash_password(password)
if username == DEFAULT_ADMIN_USERNAME:
account_id, role = OWNER_ACCOUNT_ID, ROLE_OWNER
legacy = (salt, pwd_hash, jwt_secret)
fenced = (None, None, None)
else:
account_id, role = uuid.uuid4().hex, ROLE_USER
legacy = _legacy_dummies()
fenced = (salt, pwd_hash, jwt_secret)
conn = get_connection()
try:
conn.execute(
"""
INSERT INTO auth_user (
username,
password_salt,
password_hash,
jwt_secret,
account_password_salt,
account_password_hash,
account_jwt_secret,
must_change_password,
account_id,
role,
created_at
)
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
""",
(
username,
*legacy,
*fenced,
int(must_change_password),
account_id,
role,
datetime.now(timezone.utc).isoformat(),
),
)
conn.commit()
finally:
conn.close()
from auth.policy import invalidate_account_cache
invalidate_account_cache()
def delete_user(username: str) -> None:
"""Delete a user, to roll back a failed bootstrap user creation."""
conn = get_connection()
try:
conn.execute("DELETE FROM auth_user WHERE username = ?", (username,))
conn.commit()
finally:
conn.close()
from auth.policy import invalidate_account_cache
invalidate_account_cache()
def get_user_and_secret(username: str) -> Optional[Tuple[str, str, str, bool]]:
"""Get user's password salt, hash, and JWT secret. Returns (password_salt, password_hash,
jwt_secret, must_change_password) or None."""
conn = get_connection()
try:
cur = conn.execute(
f"""
SELECT {_PASSWORD_SALT_SQL} AS password_salt, {_PASSWORD_HASH_SQL} AS password_hash,
{_SECRET_SQL} AS jwt_secret, must_change_password
FROM auth_user
WHERE username = ?
""",
(username,),
)
row = cur.fetchone()
if not row:
return None
return (
row["password_salt"],
row["password_hash"],
row["jwt_secret"],
bool(row["must_change_password"]),
)
finally:
conn.close()
def get_jwt_secret(username: str) -> Optional[str]:
conn = get_connection()
try:
cur = conn.execute(
f"SELECT {_SECRET_SQL} AS jwt_secret FROM auth_user WHERE username = ?",
(username,),
)
row = cur.fetchone()
return row["jwt_secret"] if row else None
finally:
conn.close()
def requires_password_change(username: str) -> bool:
conn = get_connection()
try:
cur = conn.execute(
"SELECT must_change_password FROM auth_user WHERE username = ?",
(username,),
)
row = cur.fetchone()
return bool(row and row["must_change_password"])
finally:
conn.close()
def load_jwt_secret() -> str:
"""Load the JWT secret from the database. Raises RuntimeError if no auth user has been created yet."""
conn = get_connection()
try:
cur = conn.execute("SELECT jwt_secret FROM auth_user LIMIT 1")
row = cur.fetchone()
if not row:
raise RuntimeError(
"Auth is not initialized. Wait for the seeded admin bootstrap to complete."
)
return row["jwt_secret"]
finally:
conn.close()
_admin_created_this_process = False
def admin_created_this_process() -> bool:
"""Use this, not ensure_default_admin()'s return value: an earlier caller may already have seeded it."""
return _admin_created_this_process
def ensure_default_admin() -> bool:
"""Seed the default admin account on first startup, using a randomly generated diceware passphrase
as the bootstrap password. Returns True when it was created in this call."""
global _admin_created_this_process
if get_user_and_secret(DEFAULT_ADMIN_USERNAME) is not None:
_load_bootstrap_password()
return False
bootstrap_pw = generate_bootstrap_password()
try:
create_initial_user(
username = DEFAULT_ADMIN_USERNAME,
password = bootstrap_pw,
jwt_secret = secrets.token_urlsafe(64),
must_change_password = True,
)
_admin_created_this_process = True
return True
except sqlite3.IntegrityError:
return False
def update_password(
username: str,
new_password: str,
*,
revoke_refresh_tokens: bool = False,
expect_password_hash: Optional[str] = None,
preserve_desktop_secret: bool = False,
) -> Optional[str]:
"""Mint with the returned JWT secret; revoke refresh tokens in the same transaction as the update."""
from .hashing import hash_password
salt, pwd_hash = hash_password(new_password)
jwt_secret = secrets.token_urlsafe(64)
columns = (
"password_salt = ?, password_hash = ?, jwt_secret = ?"
if _is_owner_name(username)
else "account_password_salt = ?, account_password_hash = ?, account_jwt_secret = ?"
)
conn = get_connection()
try:
if expect_password_hash is None:
cursor = conn.execute(
f"""
UPDATE auth_user
SET {columns}, must_change_password = 0
WHERE username = ?
""",
(salt, pwd_hash, jwt_secret, username),
)
else:
cursor = conn.execute(
f"""
UPDATE auth_user
SET {columns}, must_change_password = 0
WHERE username = ? AND {_PASSWORD_HASH_SQL} = ?
""",
(salt, pwd_hash, jwt_secret, username, expect_password_hash),
)
if revoke_refresh_tokens and cursor.rowcount > 0:
conn.execute("DELETE FROM refresh_tokens WHERE username = ?", (username,))
conn.commit()
if cursor.rowcount > 0:
clear_bootstrap_password()
if not preserve_desktop_secret:
clear_desktop_secret()
return jwt_secret
return None
finally:
conn.close()
def save_refresh_token(
token: str,
username: str,
expires_at: str,
*,
is_desktop: bool = False,
secret_gen: Optional[str] = None,
) -> None:
"""Callers that verified a credential pass its ``secret_gen``; the default may re-read a rotated one."""
token_hash = _fenced_hash(_hash_token(token), username)
conn = get_connection()
try:
if secret_gen is None:
secret_gen = _current_generation(conn, username)
conn.execute(
"""
INSERT INTO refresh_tokens (token_hash, username, expires_at, is_desktop, secret_gen)
VALUES (?, ?, ?, ?, ?)
""",
(token_hash, username, expires_at, int(is_desktop), secret_gen),
)
conn.commit()
finally:
conn.close()
def _take_refresh_token(conn: sqlite3.Connection, token: str, now: str):
"""Inside the caller's BEGIN IMMEDIATE: purge expired rows, then delete-and-return the token's
row. Returns ``(row, user)`` (the auth_user row) when the token is live and its credential
generation still matches, else None; the delete stands either way."""
conn.execute(
"DELETE FROM refresh_tokens WHERE expires_at < ?",
(now,),
)
row = conn.execute(
f"""
DELETE FROM refresh_tokens
WHERE token_hash {_FENCED_HASH_SQL} AND expires_at >= ?
RETURNING username, is_desktop, secret_gen
""",
(*_hash_candidates(_hash_token(token)), now),
).fetchone()
if row is None:
return None
user = conn.execute(
f"""
SELECT {_SECRET_SQL} AS jwt_secret, role, account_id, must_change_password
FROM auth_user WHERE username = ?
""",
(row["username"],),
).fetchone()
if user is None:
return None
secret = user["jwt_secret"]
if row["secret_gen"] is not None and row["secret_gen"] != credential_generation(secret):
return None
return row, user
def consume_refresh_token(token: str) -> Optional[Tuple[str, bool, str]]:
"""Atomically validate-and-delete a refresh token for single-use rotation. DELETE RETURNING fuses
validate and delete into one statement so two concurrent refresh requests cannot both consume
the same token. Returns ``(username, is_desktop, jwt_secret)``; the caller must mint the
replacement tokens against that secret so a rotation landing mid-refresh cannot issue a
post-rotation session from a pre-rotation token."""
now = datetime.now(timezone.utc).isoformat()
conn = get_connection()
try:
# Same transaction as the delete, else a later read could hand a new secret to an older token.
conn.execute("BEGIN IMMEDIATE")
taken = _take_refresh_token(conn, token, now)
conn.commit()
if taken is None:
return None
row, user = taken
return row["username"], bool(row["is_desktop"]), user["jwt_secret"]
finally:
conn.close()
class RotatedRefresh(NamedTuple):
username: str
is_desktop: bool
jwt_secret: str
account_id: Optional[str]
must_change_password: bool
def rotate_refresh_token(
token: str, new_token: str, new_expires_at: str
) -> Optional[RotatedRefresh]:
"""Swap tokens in one transaction: on failure, including a busy auth.db, the old token stays valid."""
from utils.account_context import ROLE_OWNER
now = datetime.now(timezone.utc).isoformat()
conn = get_connection()
try:
conn.execute("BEGIN IMMEDIATE")
taken = _take_refresh_token(conn, token, now)
if taken is None:
conn.commit()
return None
row, user = taken
username = row["username"]
is_desktop = bool(row["is_desktop"]) and user["role"] == ROLE_OWNER
secret = user["jwt_secret"]
conn.execute(
"""
INSERT INTO refresh_tokens (token_hash, username, expires_at, is_desktop, secret_gen)
VALUES (?, ?, ?, ?, ?)
""",
(
_fenced_hash(_hash_token(new_token), username),
username,
new_expires_at,
int(is_desktop),
credential_generation(secret),
),
)
conn.commit()
return RotatedRefresh(
username = username,
is_desktop = is_desktop,
jwt_secret = secret,
account_id = user["account_id"],
must_change_password = False if is_desktop else bool(user["must_change_password"]),
)
except Exception:
conn.rollback()
raise
finally:
conn.close()
def verify_refresh_token(token: str) -> Optional[Tuple[str, bool]]:
"""Verify a refresh token and return the username plus desktop marker, or None when invalid or
expired. The token is NOT consumed: it stays valid until it expires."""
token_hash = _hash_token(token)
conn = get_connection()
try:
conn.execute(
"DELETE FROM refresh_tokens WHERE expires_at < ?",
(datetime.now(timezone.utc).isoformat(),),
)
conn.commit()
cur = conn.execute(
f"""
SELECT id, username, expires_at, is_desktop, secret_gen FROM refresh_tokens
WHERE token_hash {_FENCED_HASH_SQL}
""",
_hash_candidates(token_hash),
)
row = cur.fetchone()
if row is None:
return None
if row["secret_gen"] is not None and row["secret_gen"] != _current_generation(
conn, row["username"]
):
conn.execute("DELETE FROM refresh_tokens WHERE id = ?", (row["id"],))
conn.commit()
return None
expires_at = datetime.fromisoformat(row["expires_at"])
if datetime.now(timezone.utc) > expires_at:
conn.execute("DELETE FROM refresh_tokens WHERE id = ?", (row["id"],))
conn.commit()
return None
return row["username"], bool(row["is_desktop"])
finally:
conn.close()
def revoke_user_refresh_tokens(username: str, *, account_id: Optional[str] = None) -> None:
"""Revoke refresh tokens by immutable account_id, so recreated namesakes keep sessions."""
conn = get_connection()
try:
with conn:
conn.execute("BEGIN IMMEDIATE")
if account_id is not None:
row = conn.execute(
"SELECT username FROM auth_user WHERE account_id = ?", (account_id,)
).fetchone()
if row is None or row["username"] != username:
return
conn.execute("DELETE FROM refresh_tokens WHERE username = ?", (username,))
finally:
conn.close()
def create_desktop_secret() -> str:
"""Create/rotate the local desktop credential and return it once."""
ensure_default_admin()
raw_secret = DESKTOP_SECRET_PREFIX + secrets.token_urlsafe(48)
secret_hash = _pbkdf2_desktop_secret(raw_secret)
now = datetime.now(timezone.utc).isoformat()
conn = get_connection()
try:
conn.execute(
"INSERT OR REPLACE INTO app_secrets (key, value) VALUES (?, ?)",
(_DESKTOP_SECRET_HASH_KEY, secret_hash),
)
conn.execute(
"INSERT OR REPLACE INTO app_secrets (key, value) VALUES (?, ?)",
(_DESKTOP_SECRET_CREATED_AT_KEY, now),
)
conn.commit()
return raw_secret
finally:
conn.close()
def validate_desktop_secret_with_credential(raw_secret: str) -> Optional[Tuple[str, str]]:
"""Both reads share one transaction, so the returned secret is the version the check used."""
# Shape check before KDF: unauthenticated callers must not buy KDF work.
if not desktop_secret_is_well_formed(raw_secret):
return None
secret_hash = _pbkdf2_desktop_secret(raw_secret)
conn = get_connection()
try:
conn.execute("BEGIN")
row = conn.execute(
"SELECT value FROM app_secrets WHERE key = ?",
(_DESKTOP_SECRET_HASH_KEY,),
).fetchone()
if row is None or not secrets.compare_digest(row["value"], secret_hash):
return None
jwt_secret = _current_secret(conn, DEFAULT_ADMIN_USERNAME)
if jwt_secret is None:
return None
return DEFAULT_ADMIN_USERNAME, jwt_secret
finally:
conn.rollback()
conn.close()
def validate_desktop_secret(raw_secret: str) -> Optional[str]:
verified = validate_desktop_secret_with_credential(raw_secret)
return verified[0] if verified else None
def clear_desktop_secret() -> None:
conn = get_connection()
try:
conn.execute(
"DELETE FROM app_secrets WHERE key IN (?, ?)",
(_DESKTOP_SECRET_HASH_KEY, _DESKTOP_SECRET_CREATED_AT_KEY),
)
conn.commit()
finally:
conn.close()
API_KEY_PREFIX = "sk-unsloth-"
# Name sets authority: Deep Research keys reach the saved connection, data-recipe keys only local /v1.
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"
STUDIO_CHAT_TOOLS_KEY_NAME = "Unsloth Studio chat tools"
# The same key minted for a chat an API key started: it never gets the owner's load-beside pass.
STUDIO_CHAT_TOOLS_API_KEY_NAME = "Unsloth Studio chat tools (API)"
def create_api_key(
username: str,
name: str,
expires_at: Optional[str] = None,
internal: bool = False,
expect_gen: Optional[str] = None,
account_id: Optional[str] = None,
purpose: Optional[str] = None,
) -> Tuple[str, dict]:
"""``expect_gen`` fences the insert so a password reset cannot mint a key that outlives it."""
raw_key = API_KEY_PREFIX + secrets.token_hex(16)
key_hash = _fenced_hash(_pbkdf2_api_key(raw_key), username)
key_prefix = raw_key[len(API_KEY_PREFIX) : len(API_KEY_PREFIX) + 8]
now = datetime.now(timezone.utc).isoformat()
conn = get_connection()
try:
if account_id is not None:
# A long-lived caller (a research run) may hold a name from before a rename.
row = conn.execute(
"SELECT username FROM auth_user WHERE account_id = ?", (account_id,)
).fetchone()
if row is not None:
username = row["username"]
if expect_gen is not None:
conn.execute("BEGIN IMMEDIATE")
if _current_generation(conn, username) != expect_gen:
raise CredentialRotated(
"The credential this request authenticated with was revoked."
)
if account_id is None:
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, purpose)
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
""",
(
username,
key_prefix,
key_hash,
name,
now,
expires_at,
1 if internal else 0,
account_id,
purpose,
),
)
if account_id is not None:
conn.execute(
f"""INSERT INTO account_api_keys ({_ACCOUNT_API_KEY_COLUMNS})
SELECT {_ACCOUNT_API_KEY_COLUMNS} FROM api_keys WHERE key_hash = ?""",
(key_hash,),
)
conn.commit()
cur = conn.execute("SELECT * FROM api_keys WHERE key_hash = ?", (key_hash,))
row = cur.fetchone()
return raw_key, dict(row)
finally:
conn.close()
def list_api_keys(
username: str,
include_internal: bool = False,
account_id: Optional[str] = None,
) -> list:
conn = get_connection()
try:
scope, params = _key_scope(username, account_id)
internal = "" if include_internal else " AND is_internal = 0"
cur = conn.execute(
f"""
SELECT id, username, key_prefix, name, created_at, last_used_at,
expires_at, is_active, is_internal, purpose
FROM api_keys
WHERE {scope}{internal}
ORDER BY created_at DESC
""",
params,
)
return [dict(row) for row in cur.fetchall()]
finally:
conn.close()
def _managed_account_id(conn: sqlite3.Connection, username: str) -> Optional[str]:
row = conn.execute(
"SELECT account_id, role FROM auth_user WHERE username = ?", (username,)
).fetchone()
if row is None or row["role"] in (None, "owner"):
return None
return row["account_id"]
def _revoke_key_copy(conn: sqlite3.Connection, key_id: int) -> None:
conn.execute(
"UPDATE account_api_keys SET is_active = 0 "
"WHERE key_hash = (SELECT key_hash FROM api_keys WHERE id = ?)",
(key_id,),
)
def _key_scope(username: str, account_id: Optional[str]) -> Tuple[str, tuple]:
if account_id is None:
return "username = ?", (username,)
return "username = ? AND account_id = ?", (username, account_id)
def revoke_api_key(
username: str,
key_id: int,
account_id: Optional[str] = None,
) -> bool:
"""Soft-delete an API key. Returns True if a matching row was found."""
conn = get_connection()
try:
scope, params = _key_scope(username, account_id)
cursor = conn.execute(
f"UPDATE api_keys SET is_active = 0 WHERE id = ? AND {scope}",
(key_id, *params),
)
if cursor.rowcount:
_revoke_key_copy(conn, key_id)
conn.commit()
return cursor.rowcount > 0
finally:
conn.close()
def revoke_internal_api_key(key_id: int) -> bool:
"""Revoke an internal workflow-minted key without requiring a username. Used by the recipe runner
to retire its key once the job terminates, shrinking the window a leaked key could be abused."""
conn = get_connection()
try:
cursor = conn.execute(
"UPDATE api_keys SET is_active = 0 WHERE id = ? AND is_internal = 1",
(key_id,),
)
if cursor.rowcount:
_revoke_key_copy(conn, key_id)
conn.commit()
return cursor.rowcount > 0
finally:
conn.close()
def delete_internal_api_key(key_id: int) -> bool:
"""Delete an internal key row and its account copy. For keys minted per call, which would
otherwise leave one inactive row behind for every call."""
conn = get_connection()
try:
conn.execute(
"DELETE FROM account_api_keys "
"WHERE key_hash = (SELECT key_hash FROM api_keys WHERE id = ? AND is_internal = 1)",
(key_id,),
)
cursor = conn.execute("DELETE FROM api_keys WHERE id = ? AND is_internal = 1", (key_id,))
conn.commit()
return cursor.rowcount > 0
finally:
conn.close()
def is_internal_api_key(raw_key: str) -> bool:
"""Memoized: it runs on the event loop per API-key request, and a key's origin never changes."""
if not raw_key.startswith(API_KEY_PREFIX):
return False
cache_id = _api_key_cache_id(raw_key)
cached_internal = _api_key_internal_cache.get(cache_id)
if cached_internal is not None:
return cached_internal
cached_hash = _api_key_hash_cache.get(cache_id)
key_hash = cached_hash if cached_hash is not None else _pbkdf2_api_key(raw_key)
conn = get_connection()
try:
row = conn.execute(
f"SELECT is_internal FROM api_keys WHERE key_hash {_FENCED_HASH_SQL}",
_hash_candidates(key_hash),
).fetchone()
finally:
conn.close()
if row is None:
return False
internal = bool(row["is_internal"])
with _api_key_hash_cache_lock:
if len(_api_key_hash_cache) >= _API_KEY_HASH_CACHE_MAX:
_api_key_hash_cache.clear()
_api_key_internal_cache.clear()
_api_key_hash_cache[cache_id] = key_hash
_api_key_internal_cache[cache_id] = internal
return internal
def internal_api_key_name(raw_key: str) -> Optional[str]:
"""Authorization should use this, not is_internal_api_key, which is too coarse; not memoized."""
if not raw_key.startswith(API_KEY_PREFIX):
return None
cache_id = _api_key_cache_id(raw_key)
cached_hash = _api_key_hash_cache.get(cache_id)
key_hash = cached_hash if cached_hash is not None else _pbkdf2_api_key(raw_key)
conn = get_connection()
try:
row = conn.execute(
f"SELECT name FROM api_keys WHERE key_hash {_FENCED_HASH_SQL} AND is_internal = 1 AND is_active = 1",
_hash_candidates(key_hash),
).fetchone()
finally:
conn.close()
if row is None:
return None
name = row["name"]
return name if isinstance(name, str) else None
def validate_api_key(raw_key: str) -> Optional[str]:
verified = validate_api_key_with_credential(raw_key)
return verified[0] if verified else None
def validate_api_key_with_credential(
raw_key: str, *, touch: bool = True
) -> Optional[Tuple[str, str]]:
verified = validate_api_key_account(raw_key, touch = touch)
return (verified[0]["username"], verified[1]) if verified else None
def validate_api_key_account(raw_key: str, *, touch: bool = True) -> Optional[Tuple[dict, str]]:
"""Validate *raw_key* -> ``(account record, jwt_secret)``, or ``None``. The record comes from
the matching statement, so a namesake cannot bind; ``touch=False`` skips the last-used write."""
cache_id = _api_key_cache_id(raw_key)
cached_hash = _api_key_hash_cache.get(cache_id)
key_hash = cached_hash if cached_hash is not None else _pbkdf2_api_key(raw_key)
conn = get_connection()
try:
if touch:
try:
conn.execute("BEGIN IMMEDIATE")
except sqlite3.OperationalError as exc:
if not sqlite_gate.is_busy_error(exc):
raise
# last_used_at is informational: a busy auth.db must not fail the request.
touch = False
cur = conn.execute(
f"""
SELECT k.id, k.username, k.name, k.purpose, k.is_active, k.is_internal, 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
AND (k.account_id = u.account_id OR (k.account_id IS NULL AND u.role = 'owner'))
WHERE k.key_hash {_FENCED_HASH_SQL}
""",
_hash_candidates(key_hash),
)
row = cur.fetchone()
if row is None:
return None
# Real key: memoize so later requests skip the KDF. Bounded; clear on overflow.
if cached_hash is None:
with _api_key_hash_cache_lock:
if len(_api_key_hash_cache) >= _API_KEY_HASH_CACHE_MAX:
_api_key_hash_cache.clear()
# Clear both caches together; the origin cache is sized against the hash cache.
_api_key_internal_cache.clear()
_api_key_hash_cache[cache_id] = key_hash
if not row["is_active"]:
return None
if row["expires_at"] is not None:
expires = datetime.fromisoformat(row["expires_at"])
if datetime.now(timezone.utc) > expires:
return None
if not row["account_active"]:
return None
secret = row["jwt_secret"]
if secret is None:
return None
if touch:
conn.execute(
"UPDATE api_keys SET last_used_at = ? WHERE id = ?",
(datetime.now(timezone.utc).isoformat(), row["id"]),
)
conn.commit()
record = {
"account_id": row["account_id"],
"username": row["username"],
"role": row["role"],
"is_active": int(row["account_active"]),
"expires_at": row["expires_at"],
"key_name": row["name"],
"key_purpose": row["purpose"],
"key_internal": bool(row["is_internal"]),
"key_id": row["id"],
}
return record, secret
finally:
conn.rollback()
conn.close()