From 54cbb335a8f2a22c26f0dd1eb11a130ce18df781 Mon Sep 17 00:00:00 2001 From: Mike Pasarella Date: Mon, 16 Nov 2026 11:31:42 +0100 Subject: [PATCH 1/2] feat(server): add --api-key, --api-key-file and --cors-origins --- examples/server/README.md | 11 ++++++++ examples/server/main.cpp | 49 ++++++++++++++++++++++++++++------ examples/server/runtime.cpp | 53 +++++++++++++++++++++++++++++++++++++ examples/server/runtime.h | 5 ++++ 4 files changed, 110 insertions(+), 8 deletions(-) diff --git a/examples/server/README.md b/examples/server/README.md index 8673eb80c..f57fc3f6a 100644 --- a/examples/server/README.md +++ b/examples/server/README.md @@ -420,6 +420,17 @@ configured defaults. | `--max-pending-jobs ` | `64` | Maximum async jobs queued or generating | | `--completed-ttl-seconds ` | `600` | Retention time for completed async jobs | +### Access + +By default any program on the machine, and any web page open in a browser on +it, can call the server. To limit that: + +| Option | Default | Purpose | +| --- | --- | --- | +| `--api-key ` | none | Key clients must send as `Authorization: Bearer ` or `X-Api-Key: `; comma-separated for several. Requests without a valid key get `401`. The web page at `/` stays open. | +| `--api-key-file ` | none | The same, one key per line, so keys don't show in the process list | +| `--cors-origins ` | any | Web origins allowed to call the server, comma-separated; others get no CORS headers, so browsers keep their pages out | + ### Logging Logging defaults to `info`. Use `--log-level ` to select `debug`, `verbose`, diff --git a/examples/server/main.cpp b/examples/server/main.cpp index 391a1ec9a..8414e15ba 100644 --- a/examples/server/main.cpp +++ b/examples/server/main.cpp @@ -1,3 +1,4 @@ +#include #include #include #include @@ -62,6 +63,20 @@ static void parse_args(int argc, } } +// api_key_matches compares in constant time, so the answer's timing +// doesn't tell how much of a key was right. +static bool api_key_matches(const std::vector& keys, const std::string& key) { + bool found = false; + for (const auto& k : keys) { + unsigned char diff = k.size() != key.size(); + for (size_t i = 0; i < k.size(); i++) { + diff |= static_cast(k[i] ^ (i < key.size() ? key[i] : 0)); + } + found |= diff == 0; + } + return found; +} + void sd_log_cb(enum sd_log_level_t level, const char* log, void* data) { SDSvrParams* svr_params = (SDSvrParams*)data; log_print(level, log, svr_params->log_level, svr_params->color); @@ -136,20 +151,38 @@ int main(int argc, const char** argv) { httplib::Server svr; - svr.set_pre_routing_handler([](const httplib::Request& req, httplib::Response& res) { - std::string origin = req.get_header_value("Origin"); - if (origin.empty()) { - origin = "*"; + svr.set_pre_routing_handler([&svr_params](const httplib::Request& req, httplib::Response& res) { + // CORS: with --cors-origins only those origins get the headers, so a + // browser keeps other web pages out; without it, any origin (as before). + const auto& allowed = svr_params.cors_origins; + std::string origin = req.get_header_value("Origin"); + if (allowed.empty() || std::find(allowed.begin(), allowed.end(), origin) != allowed.end()) { + res.set_header("Access-Control-Allow-Origin", origin.empty() ? "*" : origin); + res.set_header("Access-Control-Allow-Credentials", "true"); + res.set_header("Access-Control-Allow-Methods", "*"); + res.set_header("Access-Control-Allow-Headers", "*"); } - res.set_header("Access-Control-Allow-Origin", origin); - res.set_header("Access-Control-Allow-Credentials", "true"); - res.set_header("Access-Control-Allow-Methods", "*"); - res.set_header("Access-Control-Allow-Headers", "*"); if (req.method == "OPTIONS") { res.status = 204; return httplib::Server::HandlerResponse::Handled; } + + // API key: every request but the web page itself needs one. + if (!svr_params.api_keys.empty() && !(req.method == "GET" && req.path == "/")) { + std::string key = req.get_header_value("X-Api-Key"); + const std::string auth = req.get_header_value("Authorization"); + const std::string bearer = "Bearer "; + if (key.empty() && auth.compare(0, bearer.size(), bearer) == 0) { + key = auth.substr(bearer.size()); + } + if (!api_key_matches(svr_params.api_keys, key)) { + res.status = 401; + res.set_content(R"({"error":{"code":401,"message":"Invalid API Key","type":"authentication_error"}})", + "application/json"); + return httplib::Server::HandlerResponse::Handled; + } + } return httplib::Server::HandlerResponse::Unhandled; }); diff --git a/examples/server/runtime.cpp b/examples/server/runtime.cpp index 6ac3866c7..06a04c54e 100644 --- a/examples/server/runtime.cpp +++ b/examples/server/runtime.cpp @@ -6,6 +6,7 @@ #include #include #include +#include #include #include #include @@ -392,8 +393,39 @@ ArgOptions SDSvrParams::get_options() { return -1; }; + auto split_list = [](const char* arg, std::vector& out) { + std::stringstream ss(arg); + std::string item; + while (std::getline(ss, item, ',')) { + if (!item.empty()) { + out.push_back(item); + } + } + }; + options.manual_options = { {"-h", "--help", "show this help message and exit", on_help_arg}, + {"", "--api-key", "API key clients must send (Authorization: Bearer KEY or X-Api-Key); comma-separated for several", + [this, split_list](int argc, const char** argv, int index) { + if (++index >= argc || argv[index][0] == '\0') + return -1; + split_list(argv[index], api_keys); + return 1; + }}, + {"", "--api-key-file", "file with API keys, one per line (keeps them off the command line)", + [this](int argc, const char** argv, int index) { + if (++index >= argc || argv[index][0] == '\0') + return -1; + api_key_file = argv_to_utf8(index, argv); + return 1; + }}, + {"", "--cors-origins", "web origins allowed to call the server, comma-separated (default: any)", + [this, split_list](int argc, const char** argv, int index) { + if (++index >= argc || argv[index][0] == '\0') + return -1; + split_list(argv[index], cors_origins); + return 1; + }}, {"", "--model-dir", "model root; repeat to search multiple directories (default: models)", [this](int argc, const char** argv, int index) { if (++index >= argc || argv[index][0] == '\0') @@ -438,6 +470,25 @@ bool SDSvrParams::resolve_and_validate() { if (!validate()) { return false; } + if (!api_key_file.empty()) { + std::ifstream file(fs::u8path(api_key_file)); + if (!file) { + LOG_ERROR("error: can't read api_key_file: %s", api_key_file.c_str()); + return false; + } + std::string line; + while (std::getline(file, line)) { + line.erase(line.find_last_not_of(" \t\r\n") + 1); + line.erase(0, line.find_first_not_of(" \t")); + if (!line.empty()) { + api_keys.push_back(line); + } + } + if (api_keys.empty()) { + LOG_ERROR("error: api_key_file has no keys: %s", api_key_file.c_str()); + return false; + } + } return true; } @@ -450,6 +501,8 @@ std::string SDSvrParams::to_string() const { << " max_pending_jobs: " << max_pending_jobs << ",\n" << " completed_ttl_seconds: " << completed_ttl_seconds << ",\n" << " serve_html_path: \"" << serve_html_path << "\",\n" + << " api_keys: " << api_keys.size() << ",\n" + << " cors_origins: " << cors_origins.size() << ",\n" << "}"; return oss.str(); } diff --git a/examples/server/runtime.h b/examples/server/runtime.h index abb9766f7..d6f6cbaa1 100644 --- a/examples/server/runtime.h +++ b/examples/server/runtime.h @@ -26,6 +26,11 @@ struct SDSvrParams { int completed_ttl_seconds = 600; std::string serve_html_path; std::vector model_dirs; + // Access: keys clients must send, and the web origins that may call the + // server. Empty: no key needed, any origin (as before). + std::vector api_keys; + std::string api_key_file; + std::vector cors_origins; bool normal_exit = false; sd_log_level_t log_level = SD_LOG_INFO; bool color = false; From 0fade58ede17f72827ea4b9fa0cd51e6f86688a5 Mon Sep 17 00:00:00 2001 From: Mike Pasarella Date: Mon, 16 Nov 2026 11:53:44 +0100 Subject: [PATCH 2/2] fix(server): address review of the access options - allow the headers a preflight asks for (Authorization isn't covered by a wildcard when credentials are allowed) - an empty --api-key or --cors-origins list, or a key file without keys, stops the server at startup instead of leaving it open - README: the bundled Web UI can't send a key; --cors-origins limits who may read answers, a key is what refuses requests --- examples/server/README.md | 14 ++++++++++++-- examples/server/main.cpp | 5 ++++- examples/server/runtime.cpp | 19 ++++++++++++++++--- 3 files changed, 32 insertions(+), 6 deletions(-) diff --git a/examples/server/README.md b/examples/server/README.md index f57fc3f6a..f654ed5f8 100644 --- a/examples/server/README.md +++ b/examples/server/README.md @@ -427,9 +427,19 @@ it, can call the server. To limit that: | Option | Default | Purpose | | --- | --- | --- | -| `--api-key ` | none | Key clients must send as `Authorization: Bearer ` or `X-Api-Key: `; comma-separated for several. Requests without a valid key get `401`. The web page at `/` stays open. | +| `--api-key ` | none | Key clients must send as `Authorization: Bearer ` or `X-Api-Key: `; comma-separated for several. Requests without a valid key get `401`. | | `--api-key-file ` | none | The same, one key per line, so keys don't show in the process list | -| `--cors-origins ` | any | Web origins allowed to call the server, comma-separated; others get no CORS headers, so browsers keep their pages out | +| `--cors-origins ` | any | Web origins allowed to read the server's answers in a browser, comma-separated | + +With a key, the page at `/` still loads, but the bundled Web UI can't send +the key, so its calls get `401`; it is meant for use without a key. + +`--cors-origins` only decides which web pages may read the answers: other +pages get no CORS headers, but their requests still reach the server. To +refuse requests, set a key as well. + +An empty list (such as `--api-key ,`) or a key file without keys stops the +server at startup instead of leaving it open. ### Logging diff --git a/examples/server/main.cpp b/examples/server/main.cpp index 8414e15ba..3daeec77f 100644 --- a/examples/server/main.cpp +++ b/examples/server/main.cpp @@ -160,7 +160,10 @@ int main(int argc, const char** argv) { res.set_header("Access-Control-Allow-Origin", origin.empty() ? "*" : origin); res.set_header("Access-Control-Allow-Credentials", "true"); res.set_header("Access-Control-Allow-Methods", "*"); - res.set_header("Access-Control-Allow-Headers", "*"); + // With credentials, browsers take "*" literally and never let + // Authorization through a wildcard: name the headers asked for. + std::string headers = req.get_header_value("Access-Control-Request-Headers"); + res.set_header("Access-Control-Allow-Headers", headers.empty() ? "*" : headers); } if (req.method == "OPTIONS") { diff --git a/examples/server/runtime.cpp b/examples/server/runtime.cpp index 06a04c54e..2877fcf0e 100644 --- a/examples/server/runtime.cpp +++ b/examples/server/runtime.cpp @@ -393,14 +393,20 @@ ArgOptions SDSvrParams::get_options() { return -1; }; + // split_list adds the comma-separated entries of arg to out; a list + // without any entry (like ",") is an error, so a restriction can't + // silently turn into none. auto split_list = [](const char* arg, std::vector& out) { std::stringstream ss(arg); std::string item; + size_t added = 0; while (std::getline(ss, item, ',')) { if (!item.empty()) { out.push_back(item); + added++; } } + return added > 0; }; options.manual_options = { @@ -409,7 +415,10 @@ ArgOptions SDSvrParams::get_options() { [this, split_list](int argc, const char** argv, int index) { if (++index >= argc || argv[index][0] == '\0') return -1; - split_list(argv[index], api_keys); + if (!split_list(argv[index], api_keys)) { + LOG_ERROR("error: --api-key needs at least one key"); + return -1; + } return 1; }}, {"", "--api-key-file", "file with API keys, one per line (keeps them off the command line)", @@ -423,7 +432,10 @@ ArgOptions SDSvrParams::get_options() { [this, split_list](int argc, const char** argv, int index) { if (++index >= argc || argv[index][0] == '\0') return -1; - split_list(argv[index], cors_origins); + if (!split_list(argv[index], cors_origins)) { + LOG_ERROR("error: --cors-origins needs at least one origin"); + return -1; + } return 1; }}, {"", "--model-dir", "model root; repeat to search multiple directories (default: models)", @@ -477,6 +489,7 @@ bool SDSvrParams::resolve_and_validate() { return false; } std::string line; + const size_t before = api_keys.size(); while (std::getline(file, line)) { line.erase(line.find_last_not_of(" \t\r\n") + 1); line.erase(0, line.find_first_not_of(" \t")); @@ -484,7 +497,7 @@ bool SDSvrParams::resolve_and_validate() { api_keys.push_back(line); } } - if (api_keys.empty()) { + if (api_keys.size() == before) { LOG_ERROR("error: api_key_file has no keys: %s", api_key_file.c_str()); return false; }