FreeToken brings datacenter-scale model serving to your desktop. Run massive models locally, fast and efficiently.
feat(server): add --api-key authentication (#639)
Xiaoze Fan95281904548d
diff --git a/docs/cli.md b/docs/cli.mdindex b9be878c..a15a34b7 100644--- a/docs/cli.md+++ b/docs/cli.md@@ -41,6 +41,7 @@ parsers all resolve automatically from the checkpoint and the GPU.|---|---|---|| `--host` | 127.0.0.1 | Bind address || `--port` | 1919 | Bind port |+| `--api-key` | `$FREETOKEN_API_KEY`, else off | Require the key on every route except `/health`, as `Authorization: Bearer <key>` or `x-api-key: <key>`; other requests get a 401 || `--gpu` | GPU 0 | GPU to run on: a UUID from `nvidia-smi -L` or an `nvidia-smi` index; see [below](#choosing-a-gpu) || `--max-running-requests` | 4 | Max concurrently running requests || `--max-output-tokens` | 32768 | Default output budget for requests that omit one |@@ -131,14 +132,17 @@ ft shell --model ~/models/Qwen3.6-35B-A3B # serve + chat in one process```- Attach mode talks to `--server URL` (default `http://127.0.0.1:1919`)+- `--api-key KEY` (default `$FREETOKEN_API_KEY`) attaches to a server started with `--api-key`; with `--model` the shell uses that server's own key- `/help` inside the shell lists the commands (`/think`, `/cache`, `/reset`).## ft ctl```bash-ft ctl [--base-url http://127.0.0.1:1919] [--timeout 10] [--json] <subcommand>+ft ctl [--base-url http://127.0.0.1:1919] [--api-key KEY] [--timeout 10] [--json] <subcommand>```+`--api-key` defaults to `$FREETOKEN_API_KEY`.+| Subcommand | Endpoint | Purpose ||---|---|---|| `health` | `GET /health` | Server status, model, load progress |@@ -166,6 +170,7 @@ Code and Hermes need no declaration.| Flag | Meaning ||---|---|| `--server URL` | Server to point the agent at (default `http://127.0.0.1:1919`) |+| `--api-key KEY` | Key of a server started with `--api-key` (default `$FREETOKEN_API_KEY`). The agent gets it in its environment; Hermes and OpenClaw keep it in their config files || `--dry-run` | Print the planned config changes and command, touch nothing || `-y`, `--yes` | Approve install/config prompts || `--config` | Configure without launching |diff --git a/python/freetoken/control_cli.py b/python/freetoken/control_cli.pyindex 50a32aae..e33eb4ac 100644--- a/python/freetoken/control_cli.py+++ b/python/freetoken/control_cli.py@@ -10,6 +10,8 @@ import urllib.requestfrom collections.abc import Sequencefrom typing import Any+from freetoken.launch import resolve_api_key+DEFAULT_BASE_URL = "http://127.0.0.1:1919"# (CLI dest, pool, rebuild body key). moe/mamba are slot counts and pass straight through;@@ -74,6 +76,7 @@ def _request_json(body: dict[str, Any] | None = None,query: dict[str, Any] | None = None,timeout: float = 10.0,+ api_key: str | None,) -> dict[str, Any]:with _open_request(method,@@ -83,6 +86,7 @@ def _request_json(query=query,accept="application/json",timeout=timeout,+ api_key=api_key,) as response:raw = response.read()@@ -104,6 +108,7 @@ def _request_sse_text(*,body: dict[str, Any] | None = None,timeout: float = 10.0,+ api_key: str | None,) -> str:with _open_request(method,@@ -112,6 +117,7 @@ def _request_sse_text(body=body,accept="text/event-stream",timeout=timeout,+ api_key=api_key,) as response:return _read_sse_text(response)@@ -125,9 +131,12 @@ def _open_request(query: dict[str, Any] | None = None,accept: str,timeout: float,+ api_key: str | None,) -> Any:data = Noneheaders = {"Accept": accept}+ if api_key:+ headers["Authorization"] = f"Bearer {api_key}"if body is not None:data = json.dumps(body).encode("utf-8")headers["Content-Type"] = "application/json"@@ -284,6 +293,10 @@ def _build_parser(prog: str) -> argparse.ArgumentParser:default=DEFAULT_BASE_URL,help=f"FreeToken server URL (default: {DEFAULT_BASE_URL})",)+ parser.add_argument(+ "--api-key",+ help="API key of a server started with --api-key (default: $FREETOKEN_API_KEY)",+ )parser.add_argument("--timeout", type=float, default=10.0, help="HTTP timeout in seconds")parser.add_argument("--json", action="store_true", help="Print raw JSON response")@@ -355,14 +368,19 @@ def main(argv: Sequence[str] | None = None, *, prog: str = "ft ctl") -> int:args = parser.parse_args(list(argv) if argv is not None else None)except SystemExit as exc:return int(exc.code) if isinstance(exc.code, int) else 2+ args.api_key = resolve_api_key(args.api_key)try:if args.command == "health":- doc = _request_json("GET", args.base_url, "/health", timeout=args.timeout)+ doc = _request_json(+ "GET", args.base_url, "/health", timeout=args.timeout, api_key=args.api_key+ )_print_doc(doc, _format_health, raw_json=args.json)return 0if args.command == "stats":- doc = _request_json("GET", args.base_url, "/v1/stats", timeout=args.timeout)+ doc = _request_json(+ "GET", args.base_url, "/v1/stats", timeout=args.timeout, api_key=args.api_key+ )_print_doc(doc, _format_stats, raw_json=args.json)return 0if args.command == "generate":@@ -376,6 +394,7 @@ def main(argv: Sequence[str] | None = None, *, prog: str = "ft ctl") -> int:"ignore_eos": args.ignore_eos,},timeout=args.timeout,+ api_key=args.api_key,)if args.json:print(json.dumps({"text": text}, ensure_ascii=False, indent=2, sort_keys=True))@@ -390,13 +409,16 @@ def main(argv: Sequence[str] | None = None, *, prog: str = "ft ctl") -> int:"/v1/requests",query=query,timeout=args.timeout,+ api_key=args.api_key,)_print_doc(doc, _format_requests, raw_json=args.json)return 0if args.command == "cache" and args.cache_command in (None, "status"):if args.cache_command is None and _cache_targets(args):return _run_cache_rebuild(args)- doc = _request_json("GET", args.base_url, "/v1/cache/status", timeout=args.timeout)+ doc = _request_json(+ "GET", args.base_url, "/v1/cache/status", timeout=args.timeout, api_key=args.api_key+ )_print_doc(doc, _format_cache_status, raw_json=args.json)return 0if args.command == "cache" and args.cache_command == "rebuild":@@ -444,7 +466,9 @@ def _run_cache_rebuild(args: argparse.Namespace) -> int:print("error: cache rebuild requires at least one cache target", file=sys.stderr)return 2# The token targets can only be converted against the live geometry, so read it first.- status = _request_json("GET", args.base_url, "/v1/cache/status", timeout=args.timeout)+ status = _request_json(+ "GET", args.base_url, "/v1/cache/status", timeout=args.timeout, api_key=args.api_key+ )body = _rebuild_body(targets, status.get("geometry") or {})body["timeout"] = args.waitdoc = _request_json(@@ -453,6 +477,7 @@ def _run_cache_rebuild(args: argparse.Namespace) -> int:"/v1/cache/rebuild",body=body,timeout=args.wait + args.timeout,+ api_key=args.api_key,)if args.json or doc.get("status") != "ok":_print_doc(doc, _format_rebuild, raw_json=args.json)@@ -462,7 +487,9 @@ def _run_cache_rebuild(args: argparse.Namespace) -> int:# /cache prints. Best-effort -- the rebuild already succeeded.print("status=ok")try:- print(_format_cache_status(_request_json("GET", args.base_url, "/v1/cache/status")))+ print(_format_cache_status(+ _request_json("GET", args.base_url, "/v1/cache/status", api_key=args.api_key)+ ))except ControlCliError:passreturn 0diff --git a/python/freetoken/daemon/README.md b/python/freetoken/daemon/README.mdindex ea3b016e..ebe4a170 100644--- a/python/freetoken/daemon/README.md+++ b/python/freetoken/daemon/README.md@@ -60,9 +60,9 @@ Target a non-default daemon with `--url http://host:1900` (or `$FREETOKEN_DAEMON| Method / path | Notes || --- | --- || `GET /health` | Daemon self-health; always answers, never gated by `--token`. |-| `POST /engine/start` `{model,port,args[]}` | Idempotent on the full `(model,port,args)`; a differing config on the same port → `409`. |+| `POST /engine/start` `{model,port,args[],apiKey?}` | Idempotent on the full `(model,port,args,apiKey)`; a differing config on the same port → `409`. || `POST /engine/stop` `{force?:false}` | Close admission, drain/abort, durably enqueue the final-accounting receipt, then `SIGTERM`→grace→`SIGKILL`. A prepare/outbox failure preserves the engine. |-| `POST /engine/switch` `{model,port,args[],force?:false}` | One serialized stop-accounting-start transaction. |+| `POST /engine/switch` `{model,port,args[],apiKey?,force?:false}` | One serialized stop-accounting-start transaction. || `GET /engine/status` | `{running,pid,model,port,uptimeS,lastExitCode,…}`; outlives any single serve. || `GET /engine/logs?since=` | SSE, ANSI-stripped, tqdm-`\r` collapsed, ring replay, `id:<seq>`, `Last-Event-ID` resume. || `GET /engine/metrics` | `{ramBytes,vramBytes}` — the serve tree's own footprint only. |@@ -75,6 +75,13 @@ Target a non-default daemon with `--url http://host:1900` (or `$FREETOKEN_DAEMONSet `--token` (or `$FREETOKEN_DAEMON_TOKEN`) to require an `X-FT-Token` header on everythingexcept `/health`.+`apiKey` is the serve's own `--api-key`. The daemon hands it to the serve as `FREETOKEN_API_KEY` in+its environment (never on its command line), sends it on its own calls to the serve, and keeps it in+the owner-only state file so a re-adopted serve stays reachable. The daemon's own+`FREETOKEN_API_KEY` is never passed down: a serve requires a key only when its start request carries+one, and an `--api-key` inside `args` is rejected with a 400 because the daemon would not know it.+`ft daemon start|switch --api-key KEY` (default `$FREETOKEN_API_KEY`) sets it.+The daemon reaches the serve's destructive `POST /v1/admin/prepare-stop` endpoint only overloopback; the serve rejects non-loopback callers even when its inference API is bound to`0.0.0.0`. `force` is never implicit: it is an explicit recovery choice that may record nulldiff --git a/python/freetoken/daemon/app.py b/python/freetoken/daemon/app.pyindex d7a0a53c..dd506f78 100644--- a/python/freetoken/daemon/app.py+++ b/python/freetoken/daemon/app.py@@ -30,6 +30,7 @@ class StartBody(BaseModel):model: strport: int | None = Noneargs: list[str] = []+ apiKey: str | None = Noneclass StopBody(BaseModel):@@ -161,6 +162,15 @@ def build_app(st = manager.status()return st.get("port") or default_serve_port+ def reject_api_key_arg(args: list[str]) -> None:+ # the daemon must know the key to reach the serve, so the key only travels as apiKey+ # argparse also accepts any unambiguous prefix, and no other serve flag starts with --ap+ flags = (a.split("=", 1)[0] for a in args)+ if any(len(f) >= 4 and "--api-key".startswith(f) for f in flags):+ raise HTTPException(+ status_code=400, detail="pass the serve's API key as apiKey, not in args"+ )+def accounting_error(exc: Exception) -> JSONResponse:code = ("accounting_outbox_failed"@@ -192,9 +202,17 @@ def build_app(@app.post("/engine/start", dependencies=auth)async def engine_start(body: StartBody):+ reject_api_key_arg(body.args)port = resolve_port(body.port)try:- return await run(lifecycle_pool, manager.start, body.model, port, list(body.args))+ return await run(+ lifecycle_pool,+ manager.start,+ body.model,+ port,+ list(body.args),+ body.apiKey or None,+ )except Conflict as exc:st = manager.status()return JSONResponse(@@ -236,6 +254,7 @@ def build_app(@app.post("/engine/switch", dependencies=auth)async def engine_switch(body: SwitchBody):+ reject_api_key_arg(body.args)port = resolve_port(body.port)try:return await run(@@ -245,6 +264,7 @@ def build_app(port,list(body.args),body.force,+ body.apiKey or None,)except (AccountingPrepareError, AccountingOutboxError) as exc:return accounting_error(exc)diff --git a/python/freetoken/daemon/client.py b/python/freetoken/daemon/client.pyindex 6616778e..9ded9627 100644--- a/python/freetoken/daemon/client.py+++ b/python/freetoken/daemon/client.py@@ -16,6 +16,8 @@ import urllib.requestfrom collections.abc import Sequencefrom typing import Any+from freetoken.launch import resolve_api_key+DEFAULT_URL = "http://127.0.0.1:1900"DEFAULT_TIMEOUT = 10.0# prepare-stop (15s transport budget) + default SIGTERM grace (10s) + reap wait (10s),@@ -144,6 +146,10 @@ def _build_parser(prog: str) -> argparse.ArgumentParser:sp = sub.add_parser(name, parents=[common], help=f"POST /engine/{name}")sp.add_argument("model", help="Model path/id")sp.add_argument("--port", type=int, default=None, help="Serve port")+ sp.add_argument(+ "--api-key",+ help="API key the serve requires, set in its environment (default: $FREETOKEN_API_KEY)",+ )if name == "switch":sp.add_argument("--force",@@ -181,6 +187,8 @@ def main(argv: Sequence[str] | None = None, *, prog: str = "ft daemon") -> int:body: dict[str, Any] = {"model": args.model, "args": list(args.serve_args)}if args.port is not None:body["port"] = args.port+ if api_key := resolve_api_key(args.api_key):+ body["apiKey"] = api_keyif args.verb == "switch" and args.force:body["force"] = Truemethod, path = "POST", f"/engine/{args.verb}"diff --git a/python/freetoken/daemon/pidfile.py b/python/freetoken/daemon/pidfile.pyindex 89ffc2b4..b9865a83 100644--- a/python/freetoken/daemon/pidfile.py+++ b/python/freetoken/daemon/pidfile.py@@ -4,15 +4,16 @@open for the daemon's whole life. flock (not a bare port-bind) avoids TIME_WAIT races and isreleased automatically if the daemon dies, so a crashed daemon never wedges its own restart.-``ServeStateStore`` persists ``{model, port, pid, args, starttime, logPath}`` as JSON on every+``ServeStateStore`` persists ``{model, port, pid, args, starttime, log_path, api_key}`` as JSON on everylifecycle change, so a restarted daemon can re-adopt a still-running serve. ``starttime`` +-``args`` are what make re-adoption PID-reuse-safe and config-exact."""+``args`` are what make re-adoption PID-reuse-safe and config-exact.+The file is owner-only because it holds the serve's API key."""from __future__ import annotationsimport jsonimport os-from dataclasses import asdict, dataclass+from dataclasses import asdict, dataclass, fieldclass AlreadyRunning(RuntimeError):@@ -63,6 +64,7 @@ class ServeState:args: list[str]starttime: int | None = Nonelog_path: str | None = None+ api_key: str | None = field(default=None, repr=False)class ServeStateStore:@@ -72,7 +74,12 @@ class ServeStateStore:def save(self, state: ServeState) -> None:os.makedirs(os.path.dirname(self.path) or ".", exist_ok=True)tmp = f"{self.path}.tmp"- with open(tmp, "w") as fh:+ # unlink first: O_CREAT applies the 0o600 mode only to a file it creates+ try:+ os.remove(tmp)+ except FileNotFoundError:+ pass+ with os.fdopen(os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600), "w") as fh:json.dump(asdict(state), fh)fh.flush()os.fsync(fh.fileno())@@ -102,6 +109,7 @@ class ServeStateStore:args=list(doc.get("args") or []),starttime=doc.get("starttime"),log_path=doc.get("log_path"),+ api_key=doc.get("api_key"),)except (KeyError, TypeError, ValueError):return Nonediff --git a/python/freetoken/daemon/proxy.py b/python/freetoken/daemon/proxy.pyindex 9e382a4d..c4f0ba28 100644--- a/python/freetoken/daemon/proxy.py+++ b/python/freetoken/daemon/proxy.py@@ -49,6 +49,7 @@ class ServeProbe:now: Callable[[], float] = time.monotonic,opener: Callable[[str, float], dict] | None = None,prepare_opener: Callable[[str, float], dict] | None = None,+ api_key: Callable[[], str | None] = lambda: None,) -> None:self._host = hostself._ttl = ttl_s@@ -57,6 +58,7 @@ class ServeProbe:self._now = nowself._opener = opener or self._urlopenself._prepare_opener = prepare_opener or self._urlopen_prepare+ self._api_key = api_keyself._lock = threading.Lock()self._cache: dict[tuple[str, int], tuple[float, dict]] = {}@@ -109,19 +111,23 @@ class ServeProbe:result["reachable"] = Truereturn result- @staticmethod- def _urlopen(url: str, timeout: float) -> dict:- req = urllib.request.Request(url, headers={"Accept": "application/json"}, method="GET")+ def _headers(self) -> dict[str, str]:+ headers = {"Accept": "application/json"}+ if key := self._api_key():+ headers["Authorization"] = f"Bearer {key}"+ return headers++ def _urlopen(self, url: str, timeout: float) -> dict:+ req = urllib.request.Request(url, headers=self._headers(), method="GET")with urllib.request.urlopen(req, timeout=timeout) as resp:raw = resp.read()return json.loads(raw.decode("utf-8"))- @staticmethod- def _urlopen_prepare(url: str, timeout: float) -> dict:+ def _urlopen_prepare(self, url: str, timeout: float) -> dict:req = urllib.request.Request(url,data=b"{}",- headers={"Accept": "application/json", "Content-Type": "application/json"},+ headers={**self._headers(), "Content-Type": "application/json"},method="POST",)with urllib.request.urlopen(req, timeout=timeout) as resp:diff --git a/python/freetoken/daemon/serve_manager.py b/python/freetoken/daemon/serve_manager.pyindex 681bdef4..9d5e51fe 100644--- a/python/freetoken/daemon/serve_manager.py+++ b/python/freetoken/daemon/serve_manager.py@@ -26,6 +26,8 @@ import timefrom dataclasses import dataclassfrom typing import Any, Callable+from freetoken.launch import API_KEY_ENV+from . import osprocfrom .accounting import (AccountingOutbox,@@ -37,7 +39,7 @@ from .accounting import (class Conflict(RuntimeError):- """A different serve (model/port/args) is already running; the client should switch()."""+ """A different serve (model/port/args/key) is already running; the client should switch()."""@dataclass@@ -128,7 +130,14 @@ def build_serve_command(return argv, log_path-def spawn_serve(argv: list[str], log_path: str) -> PopenChild:+def serve_env(api_key: str | None) -> dict[str, str]:+ env = {k: v for k, v in os.environ.items() if k != API_KEY_ENV}+ if api_key:+ env[API_KEY_ENV] = api_key+ return env+++def spawn_serve(argv: list[str], log_path: str, api_key: str | None = None) -> PopenChild:"""Spawn the serve as a session leader with its stdout+stderr going to a real logfile fd (nevera PIPE): the file survives daemon death, so a re-adopting daemon just resumes tailing it andthe serve never writes to a dead pipe. ``start_new_session`` makes it a process@@ -138,6 +147,7 @@ def spawn_serve(argv: list[str], log_path: str) -> PopenChild:try:proc = subprocess.Popen(argv,+ env=serve_env(api_key),stdout=logf,stderr=subprocess.STDOUT,stdin=subprocess.DEVNULL,@@ -158,7 +168,7 @@ class ServeManager:ring,state_store,*,- spawn_fn: Callable[[str, int, list[str]], object] | None = None,+ spawn_fn: Callable[[str, int, list[str], str | None], object] | None = None,adopt_fn: Callable[[object], object] | None = None,tailer_factory: Callable[[object], object] | None = None,signal_fn: Callable[[int, int], None] | None = None,@@ -217,6 +227,7 @@ class ServeManager:self._model: str | None = Noneself._port: int | None = Noneself._args: list[str] = []+ self._api_key: str | None = Noneself._started_at: float | None = Noneself._last_exit: ExitInfo | None = Noneself._adopted = False@@ -232,11 +243,11 @@ class ServeManager:# ---- default factories (overridable for tests) ----- def _default_spawn(self, model: str, port: int, args: list[str]):+ def _default_spawn(self, model: str, port: int, args: list[str], api_key: str | None):argv, log_path = build_serve_command(model, port, args, python=self._python, log_dir=self._log_dir)- return spawn_serve(argv, log_path)+ return spawn_serve(argv, log_path, api_key)def _default_adopt(self, state):if not osproc.is_ft_serve_on_port(state.pid, state.port, starttime=state.starttime):@@ -256,13 +267,25 @@ class ServeManager:# ---- lifecycle ----def start(- self, model: str, port: int, args: list[str] | None = None, *, _auto: bool = False+ self,+ model: str,+ port: int,+ args: list[str] | None = None,+ api_key: str | None = None,+ *,+ _auto: bool = False,) -> dict:with self._lifecycle:- return self._start(model, port, args, _auto=_auto)+ return self._start(model, port, args, api_key, _auto=_auto)def _start(- self, model: str, port: int, args: list[str] | None = None, *, _auto: bool = False+ self,+ model: str,+ port: int,+ args: list[str] | None = None,+ api_key: str | None = None,+ *,+ _auto: bool = False,) -> dict:args = list(args or [])with self._cond:@@ -278,10 +301,13 @@ class ServeManager:self._stop_requested = False # an explicit client start clears a prior stop intentwhile True:if self._child is not None and not self._stopping:- if (self._model, self._port, self._args) == (model, port, args):+ if (self._model, self._port, self._args, self._api_key) == (+ model, port, args, api_key+ ):return {"pid": self._child.pid, "idempotent": True}raise Conflict(- f"serve already running (model={self._model!r} port={self._port}); "+ f"serve already running with a different config "+ f"(model={self._model!r} port={self._port}); "f"use switch to replace it")if self._starting:@@ -299,7 +325,7 @@ class ServeManager:child = Nonetry:- child = self._spawn_fn(model, port, args)+ child = self._spawn_fn(model, port, args, api_key)finally:if child is None:with self._cond:@@ -311,6 +337,7 @@ class ServeManager:self._model = modelself._port = portself._args = args+ self._api_key = api_keyself._started_at = self._now()self._last_exit = Noneself._adopted = getattr(child, "adopted", False)@@ -318,7 +345,7 @@ class ServeManager:self._starting = Falseself._cond.notify_all()- self._persist(child, model, port, args)+ self._persist(child, model, port, args, api_key)self._maybe_apply_oom(child.pid)self._begin_watch(child)self._emit(f"serve started (pid={child.pid} model={model} port={port})")@@ -407,10 +434,11 @@ class ServeManager:port: int,args: list[str] | None = None,force: bool = False,+ api_key: str | None = None,) -> dict:with self._lifecycle:stopped = self._stop(force=force)- started = self._start(model, port, args)+ started = self._start(model, port, args, api_key)return {**started, "accounting": stopped["accounting"]}def pending_accounting(self) -> list[dict[str, Any]]:@@ -734,6 +762,7 @@ class ServeManager:self._model = state.modelself._port = state.portself._args = list(state.args)+ self._api_key = state.api_keyself._started_at = self._now() # unknown true start; report uptime since adoptionself._last_exit = Noneself._adopted = True@@ -824,13 +853,13 @@ class ServeManager:return f"serve exited with code {info.code} (pid={child.pid})"def _restart_async(self, dead_child) -> None:- model, port, args = self._model, self._port, list(self._args)+ model, port, args, api_key = self._model, self._port, list(self._args), self._api_keyif model is None or port is None:returndef _run():try:- self.start(model, port, args, _auto=True)+ self.start(model, port, args, api_key, _auto=True)except Exception as exc: # noqa: BLE001self._emit(f"auto-restart failed: {exc}")@@ -867,6 +896,10 @@ class ServeManager:with self._cond:return list(self._args)+ def serve_api_key(self) -> str | None:+ with self._cond:+ return self._api_key+def status(self) -> dict:with self._cond:child = self._child@@ -892,7 +925,9 @@ class ServeManager:# ---- helpers ----- def _persist(self, child, model: str, port: int, args: list[str]) -> None:+ def _persist(+ self, child, model: str, port: int, args: list[str], api_key: str | None+ ) -> None:from .pidfile import ServeStateself._store.save(@@ -903,6 +938,7 @@ class ServeManager:args=list(args),starttime=getattr(child, "starttime", None),log_path=getattr(child, "log_path", None),+ api_key=api_key,))diff --git a/python/freetoken/daemon/server.py b/python/freetoken/daemon/server.pyindex d4e742b0..76e7e789 100644--- a/python/freetoken/daemon/server.py+++ b/python/freetoken/daemon/server.py@@ -132,7 +132,8 @@ def main(argv: Sequence[str] | None = None, *, prog: str = "ft daemon") -> int:ring = LogRing(capacity=args.log_capacity)store = ServeStateStore(os.path.join(state_dir, "serve.json"))- probe = ServeProbe()+ # read at call time: the running serve's key, from the manager created below+ probe = ServeProbe(api_key=lambda: manager.serve_api_key())def tailer_factory(child):log_path = getattr(child, "log_path", None)diff --git a/python/freetoken/launch.py b/python/freetoken/launch.pyindex 5aac9389..e3c42154 100644--- a/python/freetoken/launch.py+++ b/python/freetoken/launch.py@@ -5,6 +5,7 @@ import jsonimport osimport shleximport shutil+import statimport subprocessimport sysimport time@@ -20,7 +21,7 @@ DEFAULT_SERVER = "http://127.0.0.1:1919"CODEX_PROFILE = "freetoken-launch"CODEX_PROVIDER_NAME = "FreeToken"CODEX_CATALOG_NAME = "freetoken-model.json"-CODEX_PROVIDER_API_KEY_ENV = "FREETOKEN_API_KEY"+API_KEY_ENV = "FREETOKEN_API_KEY"# Used when the server reports no context length. Guessing low only costs earlier compaction.FALLBACK_CONTEXT_WINDOW = 128_000MAX_OUTPUT_TOKENS_CAP = 32_768@@ -71,6 +72,7 @@ class LaunchContext:extra_args: list[str]dry_run: boolassume_yes: bool = False+ api_key: str | None = None@dataclass(frozen=True)@@ -167,9 +169,15 @@ def resolve_server_url(server: str | None) -> ServerURL:return ServerURL(origin=origin, openai_base_url=f"{origin}/v1")-def _get_json(url: str) -> object:- request = Request(url, headers={"Accept": "application/json"})- with urlopen(request, timeout=5) as response:+def resolve_api_key(api_key: str | None) -> str | None:+ return api_key or os.environ.get(API_KEY_ENV) or None+++def _get_json(url: str, api_key: str | None) -> object:+ headers = {"Accept": "application/json"}+ if api_key:+ headers["Authorization"] = f"Bearer {api_key}"+ with urlopen(Request(url, headers=headers), timeout=5) as response:return json.loads(response.read().decode("utf-8"))@@ -177,10 +185,10 @@ def _positive_int(value: object) -> int | None:return value if isinstance(value, int) and not isinstance(value, bool) and value > 0 else None-def _stats_model(server: ServerURL) -> dict[str, object]:+def _stats_model(server: ServerURL, api_key: str | None) -> dict[str, object]:"""The /v1/stats model card; empty when the server predates it."""try:- payload = _get_json(f"{server.origin}/v1/stats")+ payload = _get_json(f"{server.origin}/v1/stats", api_key)except (HTTPError, URLError, HTTPException, OSError, TimeoutError, ValueError):return {}model = payload.get("model") if isinstance(payload, dict) else None@@ -193,11 +201,16 @@ def _input_modalities(stats_model: dict[str, object]) -> tuple[str, ...]:return ("text", *extra)-def discover_server_model(server: ServerURL) -> ServedModel:+def discover_server_model(server: ServerURL, api_key: str | None) -> ServedModel:try:- _get_json(server.openai_base_url)- payload = _get_json(f"{server.openai_base_url}/models")+ _get_json(server.openai_base_url, api_key)+ payload = _get_json(f"{server.openai_base_url}/models", api_key)except (HTTPError, URLError, HTTPException, OSError, TimeoutError) as exc:+ if isinstance(exc, HTTPError) and exc.code == 401:+ raise RuntimeError(+ f"FreeToken server at {server.origin} needs a valid API key: "+ f"pass --api-key or set {API_KEY_ENV}"+ ) from excraise RuntimeError(f"Cannot connect to FreeToken server at {server.origin}: {exc}") from excif not isinstance(payload, dict):@@ -220,7 +233,7 @@ def discover_server_model(server: ServerURL) -> ServedModel:if not models:raise RuntimeError(f"FreeToken server at {server.origin} reported no models")- stats_model = _stats_model(server)+ stats_model = _stats_model(server, api_key)if context_length is None:context_length = _positive_int(stats_model.get("ctx"))@@ -236,15 +249,22 @@ def _backup_path(path: Path) -> Path:return path.with_name(f"{path.name}.{time.time_ns()}.bak")-def _write_text_with_backup(path: Path, text: str) -> None:+def _write_text_with_backup(path: Path, text: str, *, private: bool = False) -> None:path.parent.mkdir(parents=True, exist_ok=True)if path.exists() and path.read_text() != text:- shutil.copy2(path, _backup_path(path))+ backup = _backup_path(path)+ # copy2 sets the mode only after it copies the content, so create the backup with the source mode first+ backup.touch(mode=stat.S_IMODE(path.stat().st_mode))+ shutil.copy2(path, backup)+ if private:+ # before the write, so the key never sits in a file others can read+ path.touch(mode=0o600)+ path.chmod(0o600)path.write_text(text)-def _write_json_with_backup(path: Path, value: object) -> None:- _write_text_with_backup(path, json.dumps(value, indent=2) + "\n")+def _write_json_with_backup(path: Path, value: object, *, private: bool = False) -> None:+ _write_text_with_backup(path, json.dumps(value, indent=2) + "\n", private=private)def _toml_string(value: str) -> str:@@ -371,7 +391,7 @@ def _codex_profile_text(ctx: LaunchContext, catalog_path: Path) -> str:+ f"name = {_toml_string(CODEX_PROVIDER_NAME)}\n"+ f"base_url = {_toml_string(ctx.server.openai_base_url)}\n"+ 'wire_api = "responses"\n'- + f"env_key = {_toml_string(CODEX_PROVIDER_API_KEY_ENV)}\n"+ + f"env_key = {_toml_string(API_KEY_ENV)}\n")@@ -408,7 +428,7 @@ def prepare_codex(ctx: LaunchContext) -> CommandSpec:]return CommandSpec(argv=argv,- env={CODEX_PROVIDER_API_KEY_ENV: "freetoken"},+ env={API_KEY_ENV: ctx.api_key or "freetoken"},unset_env=CODEX_CLEAR_ENV,)@@ -423,7 +443,7 @@ def prepare_claude(ctx: LaunchContext) -> CommandSpec:"CLAUDE_CODE_MAX_OUTPUT_TOKENS": str(_max_output_tokens(ctx)),"ANTHROPIC_BASE_URL": ctx.server.origin,"ANTHROPIC_API_KEY": "",- "ANTHROPIC_AUTH_TOKEN": "freetoken",+ "ANTHROPIC_AUTH_TOKEN": ctx.api_key or "freetoken","ANTHROPIC_MODEL": model_id,"ANTHROPIC_DEFAULT_OPUS_MODEL": model_id,"ANTHROPIC_DEFAULT_SONNET_MODEL": model_id,@@ -456,13 +476,16 @@ def _opencode_model_entries(def _opencode_config(ctx: LaunchContext) -> str:model_ids = _ordered_model_ids(ctx)+ options = {"baseURL": ctx.server.openai_base_url}+ if ctx.api_key:+ options["apiKey"] = ctx.api_keyconfig = {"$schema": "https://opencode.ai/config.json","provider": {OPENCODE_PROVIDER: {"npm": "@ai-sdk/openai-compatible","name": OPENCODE_PROVIDER_NAME,- "options": {"baseURL": ctx.server.openai_base_url},+ "options": options,"models": _opencode_model_entries(model_ids, _context_window(ctx), _max_output_tokens(ctx), _accepts_images(ctx)),@@ -614,7 +637,7 @@ def _patch_openclaw_config(new_models.append(entry)provider["baseUrl"] = ctx.server.openai_base_url- provider["apiKey"] = "freetoken-local"+ provider["apiKey"] = ctx.api_key or "freetoken-local"provider["api"] = "openai-completions"provider["models"] = new_modelsproviders[OPENCLAW_PROVIDER] = provider@@ -661,7 +684,9 @@ def prepare_openclaw(ctx: LaunchContext) -> CommandSpec:if not _openclaw_has_freetoken_provider(config):if not ctx.assume_yes and not _confirm_openclaw_first_patch(ctx, config_path):raise RuntimeError("OpenClaw config patch cancelled")- _write_json_with_backup(config_path, _patch_openclaw_config(ctx, config))+ _write_json_with_backup(+ config_path, _patch_openclaw_config(ctx, config), private=bool(ctx.api_key)+ )_clear_openclaw_session_overrides(ctx.model.model_id)argv = ["openclaw", *ctx.extra_args] if ctx.extra_args else ["openclaw", "chat"]@@ -697,8 +722,8 @@ def prepare_hermes(ctx: LaunchContext) -> CommandSpec:model_section["default"] = ctx.model.model_idmodel_section["provider"] = "custom"model_section["base_url"] = ctx.server.openai_base_url- # A non-empty dummy: FreeToken is unauthenticated, but some clients reject an empty key.- model_section["api_key"] = HERMES_API_KEY+ # Dummy for a server without --api-key; some clients reject an empty key.+ model_section["api_key"] = ctx.api_key or HERMES_API_KEY# Hermes' name for the window (prompt + generation). Left unset it auto-detects, and a# miss lands on a 32k default that trips the floor below.window = _context_window(ctx)@@ -712,7 +737,9 @@ def prepare_hermes(ctx: LaunchContext) -> CommandSpec:file=sys.stderr,)- _write_text_with_backup(config_path, yaml.safe_dump(config, sort_keys=False))+ _write_text_with_backup(+ config_path, yaml.safe_dump(config, sort_keys=False), private=bool(ctx.api_key)+ )argv = ["hermes", *ctx.extra_args] if ctx.extra_args else ["hermes", "chat"]return CommandSpec(argv=argv, env={})@@ -753,8 +780,7 @@ def prepare_dsh(ctx: LaunchContext) -> CommandSpec:``reasoning_content``, while llm-pi-ai's JSON round-trip can change argumentvalues and key order — drift that survives render canonicalization, cutsthe prefix cache, and shows the model a rewrite of its own output. The- dummy DEEPSEEK_API_KEY satisfies dsh's non-empty key requirement; FreeToken- itself is unauthenticated."""+ dummy DEEPSEEK_API_KEY satisfies dsh's non-empty key requirement."""settings_path = _dsh_home() / DSH_LAUNCH_SETTINGS_NAMEpatch_path = _dsh_home() / DSH_LAUNCH_PATCH_NAMEif not ctx.dry_run:@@ -774,7 +800,7 @@ def prepare_dsh(ctx: LaunchContext) -> CommandSpec:window, output = _context_window(ctx), _max_output_tokens(ctx)modalities = ["text", "image"] if _accepts_images(ctx) else ["text"]- config["llm-deepseek"] = {+ section: dict[str, object] = {"baseURL": ctx.server.openai_base_url,"models": [{@@ -787,6 +813,10 @@ def prepare_dsh(ctx: LaunchContext) -> CommandSpec:for model_id in _ordered_model_ids(ctx)],}+ if ctx.api_key:+ # not DEEPSEEK_API_KEY: dsh's web search also reads it and sends it to api.deepseek.com+ section["apiKeyEnv"] = API_KEY_ENV+ config["llm-deepseek"] = sectionconfig["agent-default-model"] = {"provider": "deepseek-official","model": ctx.model.model_id,@@ -804,15 +834,14 @@ def prepare_dsh(ctx: LaunchContext) -> CommandSpec:elif len(app_args) >= 2 and app_args[0] == "--profile":profile, app_args = app_args[1], app_args[2:]argv = ["dsh", "--profile", profile, "--patch", str(patch_path), *app_args]- return CommandSpec(- argv=argv,- env={- "DEEPSEEK_BASE_URL": ctx.server.openai_base_url,- "DEEPSEEK_API_KEY": DSH_API_KEY,- "DSH_TELEMETRY_DISABLED": "1",- },- unset_env=CLOUD_PROVIDER_API_KEY_ENV,- )+ env = {+ "DEEPSEEK_BASE_URL": ctx.server.openai_base_url,+ "DEEPSEEK_API_KEY": DSH_API_KEY,+ "DSH_TELEMETRY_DISABLED": "1",+ }+ if ctx.api_key:+ env[API_KEY_ENV] = ctx.api_key+ return CommandSpec(argv=argv, env=env, unset_env=CLOUD_PROVIDER_API_KEY_ENV)PREPARERS = {@@ -840,6 +869,10 @@ def parse_argv(argv: list[str], prog: str = "python -m freetoken.launch") -> arg)parser.add_argument("agent", choices=sorted(PREPARERS))parser.add_argument("--server", help="FreeToken server origin or /v1 URL")+ parser.add_argument(+ "--api-key",+ help=f"API key of a server started with --api-key (default: ${API_KEY_ENV})",+ )parser.add_argument("--dry-run",action="store_true",@@ -1028,13 +1061,16 @@ def main(argv: list[str] | None = None, prog: str = "python -m freetoken.launch"return 0server = resolve_server_url(args.server)- model = discover_server_model(server)+ api_key = resolve_api_key(args.api_key)+ model = discover_server_model(server, api_key)plan_ctx = LaunchContext(server=server,model=model,extra_args=args.extra_args,dry_run=True,assume_yes=args.yes,+ # the plan is printed by --dry-run, so it never holds the real key+ api_key="<api-key>" if api_key else None,)spec = PREPARERS[args.agent](plan_ctx)if args.dry_run:@@ -1052,6 +1088,7 @@ def main(argv: list[str] | None = None, prog: str = "python -m freetoken.launch"extra_args=args.extra_args,dry_run=False,assume_yes=args.yes,+ api_key=api_key,)spec = PREPARERS[args.agent](ctx)if binary_path != spec.argv[0]:diff --git a/python/freetoken/server/api_server.py b/python/freetoken/server/api_server.pyindex 34221cfc..a9b16adf 100644--- a/python/freetoken/server/api_server.py+++ b/python/freetoken/server/api_server.py@@ -2,6 +2,8 @@ from __future__ import annotationsimport asyncioimport contextlib+import hashlib+import hmacimport jsonimport osimport signal@@ -34,6 +36,7 @@ from freetoken.utils import (load_generation_sampling,)from pydantic import BaseModel+from starlette.datastructures import Headersfrom .args import ServerArgsfrom .anthropic_api import register_anthropic_routes@@ -417,6 +420,39 @@ def install_cors(app: FastAPI, origins_csv: str) -> None:)+class _ApiKeyMiddleware:+ def __init__(self, app, api_key: str) -> None:+ self.app = app+ self._digest = hashlib.sha256(api_key.encode()).digest()++ def _matches(self, value: str | None) -> bool:+ # compare digests so the time taken does not depend on the key length+ return value is not None and hmac.compare_digest(+ hashlib.sha256(value.encode()).digest(), self._digest+ )++ async def __call__(self, scope, receive, send) -> None:+ if scope["type"] not in ("http", "websocket") or scope["path"] == "/health":+ return await self.app(scope, receive, send)+ headers = Headers(scope=scope)+ scheme, _, token = headers.get("authorization", "").partition(" ")+ if (scheme.lower() == "bearer" and self._matches(token)) or self._matches(+ headers.get("x-api-key")+ ):+ return await self.app(scope, receive, send)+ await JSONResponse({"error": "Unauthorized"}, status_code=401)(scope, receive, send)+++def install_api_key(app: FastAPI, api_key: str | None) -> None:+ """Require ``api_key`` on every route but /health.++ Run it before install_cors, so CORS answers preflights and adds its headers to 401s."""+ if api_key is None:+ return+ app.add_middleware(_ApiKeyMiddleware, api_key=api_key)+ logger.info("API key required on every route except /health")++app = FastAPI(title="FreeToken API Server", version=__version__, lifespan=lifespan)register_openai_routes(app, get_global_state, lambda: _MODEL_SAMPLING)register_anthropic_routes(app, get_global_state, lambda: _MODEL_SAMPLING)@@ -883,7 +919,7 @@ def _install_shell_stop_handlers() -> None:signal.signal(sig, _flag_shutdown)-def _serve_and_run_shell(host: str, port: int) -> None:+def _serve_and_run_shell(host: str, port: int, api_key: str | None) -> None:"""Shell mode: serve the API here, and attach the terminal client to it over the loopback.The shell is an ordinary API client (see ``freetoken.shell``), so shell mode is just@@ -916,7 +952,7 @@ def _serve_and_run_shell(host: str, port: int) -> None:# /health and echoes the same load progress the desktop app polls for. A ^C during that# wait is a stop, not a crash -- exit through the teardown below, not a traceback.with contextlib.suppress(KeyboardInterrupt):- asyncio.run(run_shell(origin, connect_grace=30.0))+ asyncio.run(run_shell(origin, connect_grace=30.0, api_key=api_key))finally:server.should_exit = Truethread.join(timeout=15)@@ -958,6 +994,7 @@ def run_api_server(config: ServerArgs, start_backend: Callable[[], "Any"], run_shost = config.server_hostport = config.server_port+ install_api_key(app, config.api_key)# Create/validate FREETOKEN_API_LOG_DIR and start the writer thread up front, so a# bad path is reported at boot rather than silently on the first request.install_cors(app, config.cors_origins)@@ -1044,7 +1081,7 @@ def run_api_server(config: ServerArgs, start_backend: Callable[[], "Any"], run_s).start()if run_shell:- _serve_and_run_shell(host, port)+ _serve_and_run_shell(host, port, config.api_key)return# uvicorn stays on the main thread (signal handling unchanged); ^C reaches the worker group.uvicorn.run(app, host=host, port=port)diff --git a/python/freetoken/server/args.py b/python/freetoken/server/args.pyindex b8d06018..5e6caa75 100644--- a/python/freetoken/server/args.py+++ b/python/freetoken/server/args.py@@ -3,7 +3,7 @@ from __future__ import annotationsimport argparseimport jsonimport os-from dataclasses import dataclass+from dataclasses import dataclass, fieldfrom typing import List, Tupleimport torch@@ -38,6 +38,8 @@ def _nvfp4_entry(value: str) -> str:class ServerArgs(SchedulerConfig):server_host: str = "127.0.0.1"server_port: int = 1919+ # kept out of repr: parse_args logs the whole ServerArgs+ api_key: str | None = field(default=None, repr=False)num_tokenizer: int = 0silent_output: bool = False# The terminal shell is attached to this server (ft shell --model / ft serve --shell-mode).@@ -368,6 +370,15 @@ def parse_args(help="The port number for the server to listen on.",)+ parser.add_argument(+ "--api-key",+ type=str,+ default=ServerArgs.api_key,+ help="Require this key on every route except /health, sent as "+ "'Authorization: Bearer <key>' or 'x-api-key: <key>'. Defaults to $FREETOKEN_API_KEY; "+ "unset serves without authentication.",+ )+parser.add_argument("--cuda-graph-max-bs","--graph",@@ -842,6 +853,13 @@ def parse_args(if entry:kwargs["quant_backend"] = entry+ # an empty flag usually means an unset shell variable; refuse it rather than serve open+ if kwargs["api_key"] == "":+ parser.error("--api-key is empty; omit it to serve without authentication")+ from freetoken.launch import resolve_api_key++ kwargs["api_key"] = resolve_api_key(kwargs["api_key"])+if kwargs["model_path"].startswith("~"):kwargs["model_path"] = os.path.expanduser(kwargs["model_path"])diff --git a/python/freetoken/shell/__init__.py b/python/freetoken/shell/__init__.pyindex e429f487..d31eed4c 100644--- a/python/freetoken/shell/__init__.py+++ b/python/freetoken/shell/__init__.py@@ -45,6 +45,10 @@ def _build_parser(prog: str) -> argparse.ArgumentParser:default=None,help="FreeToken server URL (default: $FREETOKEN_HOST, else http://127.0.0.1:1919)",)+ parser.add_argument(+ "--api-key",+ help="API key of a server started with --api-key (default: $FREETOKEN_API_KEY)",+ )return parser@@ -63,7 +67,7 @@ def main(argv: Sequence[str] | None = None, *, prog: str = "ft shell") -> int:except SystemExit as exc:return int(exc.code) if isinstance(exc.code, int) else 2- from freetoken.launch import resolve_server_url+ from freetoken.launch import resolve_api_key, resolve_server_urltry:server = resolve_server_url(parsed.server)@@ -74,7 +78,7 @@ def main(argv: Sequence[str] | None = None, *, prog: str = "ft shell") -> int:from .tui import run_shelltry:- return asyncio.run(run_shell(server.origin))+ return asyncio.run(run_shell(server.origin, api_key=resolve_api_key(parsed.api_key)))except KeyboardInterrupt:return 130diff --git a/python/freetoken/shell/client.py b/python/freetoken/shell/client.pyindex 183fa4df..d1115362 100644--- a/python/freetoken/shell/client.py+++ b/python/freetoken/shell/client.py@@ -27,7 +27,7 @@ from typing import Anyimport openaifrom openai import AsyncOpenAI-# Any string is accepted by the server; sent so the SDK doesn't refuse to build a request.+# Sent when no key is given: a server without --api-key accepts any string, and the SDK needs one.LOCAL_API_KEY = "freetoken-local"CONTROL_TIMEOUT = 10.0# Per-read timeout on the chat stream. Generous: it has to cover the gap before the first@@ -97,14 +97,15 @@ class ShellClient:self,origin: str,*,- api_key: str = LOCAL_API_KEY,+ api_key: str | None = None,timeout: float = CONTROL_TIMEOUT,) -> None:self.origin = origin.rstrip("/")self.timeout = timeout+ self._api_key = api_key or LOCAL_API_KEYself._openai = AsyncOpenAI(base_url=f"{self.origin}/v1",- api_key=api_key,+ api_key=self._api_key,max_retries=0, # a retried chat request would generate the turn twicetimeout=openai.Timeout(CHAT_READ_TIMEOUT, connect=10.0),)@@ -118,7 +119,7 @@ class ShellClient:self, method: str, path: str, body: dict[str, Any] | None, timeout: float) -> dict[str, Any]:data = None- headers = {"Accept": "application/json"}+ headers = {"Accept": "application/json", "Authorization": f"Bearer {self._api_key}"}if body is not None:data = json.dumps(body).encode("utf-8")headers["Content-Type"] = "application/json"diff --git a/python/freetoken/shell/tui.py b/python/freetoken/shell/tui.pyindex 93bd18cc..72d7ebe0 100644--- a/python/freetoken/shell/tui.py+++ b/python/freetoken/shell/tui.py@@ -515,13 +515,15 @@ def _format_load_progress(doc: dict) -> str:return f"loading ({phase})..."-async def run_shell(origin: str, *, connect_grace: float = 0.0) -> int:+async def run_shell(+ origin: str, *, connect_grace: float = 0.0, api_key: str | None = None+) -> int:"""Attach to the FreeToken server at ``origin`` and run the terminal chat.``connect_grace`` is how long to keep retrying a refused connection before giving up --left at 0 when attaching to a server the user says is already running, raised when thecaller just started one in this process (see ``server/api_server.py``)."""- client = ShellClient(origin)+ client = ShellClient(origin, api_key=api_key)try:return await _run_shell(client, origin, connect_grace=connect_grace)finally:diff --git a/tests/daemon/test_daemon_serve_manager.py b/tests/daemon/test_daemon_serve_manager.pyindex fd9956eb..cfd84ae6 100644--- a/tests/daemon/test_daemon_serve_manager.py+++ b/tests/daemon/test_daemon_serve_manager.py@@ -1,19 +1,25 @@from __future__ import annotations+import osimport signal+import sysimport threadingimport time+from concurrent.futures import ThreadPoolExecutorimport pytest+from fastapi.testclient import TestClient+from freetoken.daemon import proxyfrom freetoken.daemon.accounting import (AccountingOutbox,AccountingOutboxError,AccountingPrepareError,)+from freetoken.daemon.app import build_appfrom freetoken.daemon.logring import LogRingfrom freetoken.daemon.pidfile import ServeState, ServeStateStore-from freetoken.daemon.serve_manager import Conflict, ExitInfo, ServeManager+from freetoken.daemon.serve_manager import Conflict, ExitInfo, ServeManager, spawn_serve# --------------------------------------------------------------------------- test doubles@@ -50,11 +56,13 @@ class Spawner:def __init__(self):self.children: list[FakeChild] = []self.calls: list[tuple] = []+ self.api_keys: list[str | None] = []self._pid = 1000self.gate: threading.Event | None = None- def __call__(self, model, port, args) -> FakeChild:+ def __call__(self, model, port, args, api_key=None) -> FakeChild:self.calls.append((model, port, list(args)))+ self.api_keys.append(api_key)if self.gate is not None:self.gate.wait()self._pid += 1@@ -743,6 +751,131 @@ def test_readopt_no_state_is_noop(tmp_path):assert mgr.readopt() is False+# --------------------------------------------------------------------------- API key+++def test_api_key_is_serve_config_kept_owner_only_and_readopted(tmp_path):+ sp = Spawner()+ mgr, store, _ = make_manager(tmp_path, sp)+ # an older daemon left a world-readable state file and a stale tmp behind+ for path in (store.path, f"{store.path}.tmp"):+ with open(path, "w") as fh:+ fh.write("{}")+ os.chmod(path, 0o644)+ mgr.start("m", 1919, [], "k1")+ assert sp.api_keys == ["k1"] and mgr.serve_api_key() == "k1"+ assert mgr.start("m", 1919, [], "k1")["idempotent"] is True+ with pytest.raises(Conflict):+ mgr.start("m", 1919, [], "k2")+ assert store.load().api_key == "k1"+ assert os.stat(store.path).st_mode & 0o777 == 0o600++ adopted = FakeChild(4242, adopted=True)+ fresh = ServeManager(+ LogRing(), store, spawn_fn=Spawner(), adopt_fn=lambda state: adopted, tailer_factory=None,+ signal_fn=lambda p, s: None, apply_oom=False,+ )+ assert fresh.readopt() is True and fresh.serve_api_key() == "k1"+ adopted.die()+ sp.children[0].die()+++def test_switch_replaces_the_api_key(tmp_path):+ sp = Spawner()++ def sig(pid, s):+ if s == signal.SIGTERM:+ sp.by_pid(pid).die(0)++ mgr, store, _ = make_manager(tmp_path, sp, signal_fn=sig)+ mgr.start("m", 1919, [], "k1")+ mgr.switch("m", 1919, [], False, "k2")+ assert sp.api_keys == ["k1", "k2"]+ assert mgr.serve_api_key() == "k2" and store.load().api_key == "k2"+ sp.children[1].die()+++def test_auto_restart_keeps_the_api_key(tmp_path):+ sp = Spawner()+ mgr, _, _ = make_manager(tmp_path, sp, auto_restart=True)+ mgr.start("m", 1919, [], "k1")+ sp.children[0].die(1)+ assert wait_until(lambda: len(sp.children) == 2)+ assert sp.api_keys == ["k1", "k1"]+ sp.children[1].die()+++def test_spawned_serve_sees_only_the_requested_key(tmp_path, monkeypatch):+ monkeypatch.setenv("FREETOKEN_API_KEY", "from-daemon-env")+ code = "import os; print(os.environ.get('FREETOKEN_API_KEY'))"+ for api_key in (None, "k1"):+ log = tmp_path / f"{api_key}.log"+ child = spawn_serve([sys.executable, "-c", code], str(log), api_key)+ child.wait()+ child.close()+ assert log.read_text().strip() == str(api_key)+++def test_probe_sends_the_running_serves_key(monkeypatch):+ seen = []++ class Response:+ def __enter__(self):+ return self++ def __exit__(self, *exc):+ return False++ def read(self):+ return b"{}"++ def fake_urlopen(req, timeout):+ seen.append(req.get_header("Authorization"))+ return Response()++ monkeypatch.setattr(proxy.urllib.request, "urlopen", fake_urlopen)+ key = None+ probe = proxy.ServeProbe(api_key=lambda: key)+ probe.fresh_stats(1919)+ key = "k1"+ probe.fresh_stats(1919)+ probe.prepare_stop(1919)+ assert seen == [None, "Bearer k1", "Bearer k1"]+++def test_start_and_switch_routes_hand_the_api_key_to_the_manager():+ calls = []++ class Manager:+ def status(self):+ return {"running": False}++ def start(self, *args):+ calls.append(args)+ return {"pid": 1, "idempotent": False}++ def switch(self, *args):+ calls.append(args)+ return {"pid": 1, "idempotent": False, "accounting": None}++ with ThreadPoolExecutor(1) as lifecycle_pool, ThreadPoolExecutor(1) as proxy_pool:+ app = build_app(+ manager=Manager(), ring=LogRing(), probe=None, footprint_fn=lambda pid: {},+ lifecycle_pool=lifecycle_pool, proxy_pool=proxy_pool,+ )+ with TestClient(app) as client:+ client.post("/engine/start", json={"model": "m", "port": 1919, "apiKey": "k1"})+ client.post("/engine/start", json={"model": "m", "port": 1919, "apiKey": ""})+ client.post("/engine/start", json={"model": "m", "port": 1919})+ client.post("/engine/switch", json={"model": "m", "port": 1919, "apiKey": "k2"})+ for args in (["--api-key", "k3"], ["--api-key=k3"], ["--api", "k3"], ["--ap=k3"]):+ rejected = client.post("/engine/start", json={"model": "m", "args": args})+ assert rejected.status_code == 400+ allowed = client.post("/engine/start", json={"model": "m", "args": ["--attn", "fa"]})+ assert allowed.status_code == 200+ assert [args[-1] for args in calls] == ["k1", None, None, "k2", None]++# --------------------------------------------------------------------------- resource leak (L2)diff --git a/tests/server/test_api_key.py b/tests/server/test_api_key.pynew file mode 100644index 00000000..a655c688--- /dev/null+++ b/tests/server/test_api_key.py@@ -0,0 +1,146 @@+"""--api-key: the gate in front of every route but /health, and where the key comes from."""++from __future__ import annotations++import json+import os+import stat+from types import SimpleNamespace+from unittest.mock import patch++import pytest+import yaml+from fastapi import FastAPI+from fastapi.testclient import TestClient+from freetoken import launch+from freetoken.server.api_server import install_api_key, install_cors+from freetoken.server.args import parse_args++KEY = "sk-test"+ORIGIN = "http://localhost:1420"+++def _client(api_key: str | None) -> TestClient:+ app = FastAPI()+ app.get("/health")(lambda: {"status": "ok"})+ app.get("/v1/models")(lambda: {"data": []})+ install_api_key(app, api_key)+ install_cors(app, ORIGIN)+ return TestClient(app)+++def _parse(*argv: str):+ hf = SimpleNamespace(to_dict=lambda: {"architectures": ["Qwen3ForCausalLM"], "torch_dtype": "bfloat16"})+ with patch("freetoken.utils.cached_load_hf_config", lambda _path: hf):+ return parse_args(["--model", "/models/anon", *argv])[0]+++ "headers, status",+ [+ ({}, 401),+ ({"Authorization": "Bearer wrong"}, 401),+ ({"Authorization": f"Basic {KEY}"}, 401),+ ({"Authorization": KEY}, 401),+ ({"Authorization": b"Bearer caf\xe9"}, 401),+ ({"x-api-key": "wrong"}, 401),+ ({"Authorization": f"Bearer {KEY}"}, 200),+ ({"Authorization": f"bearer {KEY}"}, 200),+ ({"x-api-key": KEY}, 200),+ ],+)+def test_key_gates_every_route_but_health(headers, status):+ client = _client(KEY)+ response = client.get("/v1/models", headers=headers)+ assert response.status_code == status+ if status == 401:+ assert response.json() == {"error": "Unauthorized"}+ assert client.get("/health").status_code == 200+++def test_no_key_serves_open():+ assert _client(None).get("/v1/models").status_code == 200+++def test_cors_preflight_passes_and_401_carries_cors_headers():+ client = _client(KEY)+ preflight = client.options(+ "/v1/models",+ headers={"Origin": ORIGIN, "Access-Control-Request-Method": "GET",+ "Access-Control-Request-Headers": "authorization"},+ )+ assert preflight.status_code == 200+ denied = client.get("/v1/models", headers={"Origin": ORIGIN})+ assert denied.status_code == 401+ assert denied.headers["access-control-allow-origin"] == ORIGIN+++def test_options_outside_a_cors_preflight_needs_the_key():+ assert _client(KEY).options("/v1/models").status_code == 401+++def test_flag_wins_over_env_and_empty_values_do_not_enable_auth(monkeypatch):+ monkeypatch.delenv("FREETOKEN_API_KEY", raising=False)+ assert _parse().api_key is None+ monkeypatch.setenv("FREETOKEN_API_KEY", "from-env")+ assert _parse().api_key == "from-env"+ assert _parse("--api-key", KEY).api_key == KEY+ monkeypatch.setenv("FREETOKEN_API_KEY", "")+ assert _parse().api_key is None+ with pytest.raises(SystemExit):+ _parse("--api-key", "")+++def test_key_stays_out_of_the_logged_config(monkeypatch):+ monkeypatch.delenv("FREETOKEN_API_KEY", raising=False)+ assert KEY not in str(_parse("--api-key", KEY))++[email protected]("agent", sorted(launch.PREPARERS))+def test_dry_run_prints_a_placeholder_instead_of_the_key(agent, monkeypatch, capsys):+ key = 'p"w\\d\xe9'+ model = launch.ServedModel(model_id="m", models=["m"], context_length=8192)+ monkeypatch.setattr(launch, "discover_server_model", lambda _server, _key: model)+ assert launch.main([agent, "--dry-run", "--api-key", key]) == 0+ out = capsys.readouterr().out+ assert key not in out and json.dumps(key)[1:-1] not in out+ if agent in ("claude", "codex", "dsh", "opencode"):+ assert "<api-key>" in out+++def test_dsh_keeps_the_key_out_of_the_variable_its_web_search_reads(monkeypatch, tmp_path):+ monkeypatch.setenv("DSH_HOME", str(tmp_path))+ monkeypatch.setattr(launch, "_warn_dsh_node_version", lambda: None)+ ctx = launch.LaunchContext(+ server=launch.resolve_server_url("http://127.0.0.1:1919"),+ model=launch.ServedModel(model_id="m", models=["m"], context_length=8192),+ extra_args=[],+ dry_run=False,+ api_key=KEY,+ )+ env = launch.prepare_dsh(ctx).env+ settings = yaml.safe_load((tmp_path / launch.DSH_LAUNCH_SETTINGS_NAME).read_text())+ assert env["DEEPSEEK_API_KEY"] != KEY+ assert env[settings["llm-deepseek"]["apiKeyEnv"]] == KEY++[email protected]("agent", ["hermes", "openclaw"])+def test_config_files_holding_the_key_are_owner_only(agent, monkeypatch, tmp_path):+ monkeypatch.setenv("HOME", str(tmp_path))+ old_umask = os.umask(0o022)+ try:+ for key in ("sk-first", "sk-second"):+ ctx = launch.LaunchContext(+ server=launch.resolve_server_url("http://127.0.0.1:1919"),+ model=launch.ServedModel(model_id="m", models=["m"], context_length=65536),+ extra_args=[],+ dry_run=False,+ assume_yes=True,+ api_key=key,+ )+ launch.PREPARERS[agent](ctx)+ finally:+ os.umask(old_umask)+ written = [p for p in tmp_path.rglob("*") if p.is_file() and "sk-" in p.read_text()]+ assert len(written) == 2+ assert all(stat.S_IMODE(p.stat().st_mode) == 0o600 for p in written)