From ecba9ec1fca2d0a15eb7f8b34e16a48f100ab8a5 Mon Sep 17 00:00:00 2001 From: carfeii Date: Fri, 16 Oct 2026 16:40:52 +0800 Subject: [PATCH] docs: document that the admin API has no auth without admin-auth-key ADMIN_API.md documented --admin-listen-addr/--enable-namespaces but never mentioned --admin-auth-key, so following the doc as written leaves the admin API (namespace create/delete/fork, per-namespace config including jwt_key and heartbeat_url/dump_url) open to anyone who can reach the listen address, with no indication that's avoidable. DOCKER.md's own Authentication section documented SQLD_HTTP_AUTH and SQLD_AUTH_JWT_KEY_FILE but omitted LIBSQL_ADMIN_AUTH_KEY entirely. --- docs/ADMIN_API.md | 2 ++ docs/DOCKER.md | 8 ++++++++ 2 files changed, 10 insertions(+) diff --git a/docs/ADMIN_API.md b/docs/ADMIN_API.md index d5a7fe2478..c2f3cf705e 100644 --- a/docs/ADMIN_API.md +++ b/docs/ADMIN_API.md @@ -9,6 +9,8 @@ To enable the admin API, and manage namespaces, two extra flags need to be passe - `--admin-listen-addr :`: the address and port on which the admin API should listen. It must be different from the user API listen address (which defaults to port 8080). - `--enable-namespaces`: enable namespaces for the instance. By default namespaces are disabled. +**The admin API has no authentication unless you also set `--admin-auth-key ` (or the `LIBSQL_ADMIN_AUTH_KEY` environment variable).** Without it, anyone who can reach `--admin-listen-addr` can create, delete, and fork any namespace, and can rewrite a namespace's own config, including its `jwt_key` (which controls who can authenticate to that namespace's user-facing API) and `heartbeat_url`/`dump_url` (both of which cause the server to make an outbound request to a URL in the request body). Always set `--admin-auth-key` when `--admin-listen-addr` is reachable from anywhere other than a fully trusted local process, and prefer binding it to a loopback or private-network address rather than `0.0.0.0`. + ## Routes ```HTTP diff --git a/docs/DOCKER.md b/docs/DOCKER.md index 17a1ade208..5492ff80d1 100644 --- a/docs/DOCKER.md +++ b/docs/DOCKER.md @@ -77,6 +77,14 @@ the Ed25519 public key in URL-safe base64. You can also pass the key directly in the env variable SQLD_AUTH_JWT_KEY. +### `LIBSQL_ADMIN_AUTH_KEY` + +Auth key for the admin API (`SQLD_ADMIN_LISTEN_ADDR`). The admin API has no +authentication at all unless this is set, and it manages every namespace on +the instance (create/delete/fork, and per-namespace config including +`jwt_key`). If you set `SQLD_ADMIN_LISTEN_ADDR` to anything reachable outside +a fully trusted local process, set this too. See `docs/ADMIN_API.md`. + ## Environment variables ### `SQLD_NODE`