Add HTTPS support and a management-token gate for the web UI

ESP32 side can now reach the tools server over HTTPS: the Tools Server
field accepts an https:// address for a TLS-terminating reverse proxy
in front of the server (which still only ever speaks plain HTTP
itself), trusting Cloudflare's Origin CA root (embedded at build time)
since that's the common way to get a real cert on a private origin.
Every URL the device builds -- image fetch, config check, manage-menu
data, the QR codes' own links -- goes through one build_url() helper
that picks the scheme from what's configured.

Also adds an optional MANAGEMENT_TOKEN (docker-compose.yml) that gates
the web UI (/, /api/*) behind a shared secret -- unset by default, so
existing trusted-LAN deployments are unaffected. The same token is
entered once during the ESP32's captive-portal setup and gets baked
into the manage-menu's QR code (?token=...), so scanning it just works;
visiting the page without a valid token shows a plain entry prompt
instead of the config UI, and a valid query-param hit sets a cookie so
the page's own fetch()/<img> calls stay authorized for the rest of the
visit. Device-facing /frame/* endpoints are unaffected -- a separate,
already-documented trust boundary.

firmware/README.md

@@ -78,8 +78,41 @@ two-step setup screen:
 
 The config page asks for your home WiFi SSID/password and the "Tools
 Server" address (`host:port` of the [server](../server/) -- **not** your
-Immich server). Saving reboots the device, which then connects to your
-home network and starts its normal fetch/sleep cycle.
+Immich server; see below for the `https://` form). Saving reboots the
+device, which then connects to your home network and starts its normal
+fetch/sleep cycle.
+
+## HTTP vs HTTPS
+
+The Tools Server field accepts either:
+
+- `host:port` (e.g. `192.168.1.50:8420`) -- plain HTTP, talks straight to
+  the [server](../server/), which never speaks TLS itself. This is the
+  default and needs nothing extra.
+- `https://host[:port]` (e.g. `https://frame.example.com`) -- HTTPS,
+  for a TLS-terminating reverse proxy (nginx, etc.) sitting in front of
+  the server. Every URL the device builds (image fetch, config check,
+  manage-menu overlay data, the QR codes' own links) uses whichever
+  scheme you enter.
+
+The firmware only trusts one certificate authority for the HTTPS case:
+**Cloudflare's Origin CA** (both the RSA and ECC root, embedded at build
+time from [`main/certs/cloudflare_origin_ca.pem`](main/certs/cloudflare_origin_ca.pem),
+downloaded directly from Cloudflare's docs). This is the free, long-lived
+certificate Cloudflare issues for origin servers -- not a
+publicly-trusted cert, so ordinary browsers won't accept it directly, but
+it's exactly what a reverse proxy in front of a Cloudflare-proxied
+hostname presents. If your reverse proxy uses a different certificate
+(a real publicly-trusted one from Let's Encrypt, or a different private
+CA), swap the PEM file's contents for that CA's root and rebuild.
+
+The device does perform normal hostname verification (it's not skipped),
+so the Tools Server field's hostname has to match what the certificate
+was actually issued for -- a bare LAN IP address (`https://192.168.1.50`)
+will fail the handshake even with the right CA trusted, since an Origin
+CA cert never covers a raw IP. Use whatever hostname the certificate's
+SAN list actually covers (e.g. a local DNS/hosts entry pointing at the
+frame's LAN IP, or the same public hostname the proxy is issued for).
 
 ## Skipping to the next photo
 

firmware/main/CMakeLists.txt

@@ -1,3 +1,4 @@
 idf_component_register(SRCS main.c wifi_provisioning.c frame_client.c qr_onboarding.c status_screen.c epd_draw.c reset_button.c next_button.c manage_button.c manage_qr_overlay.c
                        PRIV_REQUIRES esp_event nvs_flash esp_wifi esp_netif esp_http_server esp_http_client dns_server epd7in3e qrcode epaper_fonts esp_driver_gpio
-                       EMBED_FILES root.html)
+                       EMBED_FILES root.html
+                       EMBED_TXTFILES certs/cloudflare_origin_ca.pem)

firmware/main/certs/cloudflare_origin_ca.pem

@@ -0,0 +1,40 @@
+-----BEGIN CERTIFICATE-----
+MIIEADCCAuigAwIBAgIID+rOSdTGfGcwDQYJKoZIhvcNAQELBQAwgYsxCzAJBgNV
+BAYTAlVTMRkwFwYDVQQKExBDbG91ZEZsYXJlLCBJbmMuMTQwMgYDVQQLEytDbG91
+ZEZsYXJlIE9yaWdpbiBTU0wgQ2VydGlmaWNhdGUgQXV0aG9yaXR5MRYwFAYDVQQH
+Ew1TYW4gRnJhbmNpc2NvMRMwEQYDVQQIEwpDYWxpZm9ybmlhMB4XDTE5MDgyMzIx
+MDgwMFoXDTI5MDgxNTE3MDAwMFowgYsxCzAJBgNVBAYTAlVTMRkwFwYDVQQKExBD
+bG91ZEZsYXJlLCBJbmMuMTQwMgYDVQQLEytDbG91ZEZsYXJlIE9yaWdpbiBTU0wg
+Q2VydGlmaWNhdGUgQXV0aG9yaXR5MRYwFAYDVQQHEw1TYW4gRnJhbmNpc2NvMRMw
+EQYDVQQIEwpDYWxpZm9ybmlhMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKC
+AQEAwEiVZ/UoQpHmFsHvk5isBxRehukP8DG9JhFev3WZtG76WoTthvLJFRKFCHXm
+V6Z5/66Z4S09mgsUuFwvJzMnE6Ej6yIsYNCb9r9QORa8BdhrkNn6kdTly3mdnykb
+OomnwbUfLlExVgNdlP0XoRoeMwbQ4598foiHblO2B/LKuNfJzAMfS7oZe34b+vLB
+yrP/1bgCSLdc1AxQc1AC0EsQQhgcyTJNgnG4va1c7ogPlwKyhbDyZ4e59N5lbYPJ
+SmXI/cAe3jXj1FBLJZkwnoDKe0v13xeF+nF32smSH0qB7aJX2tBMW4TWtFPmzs5I
+lwrFSySWAdwYdgxw180yKU0dvwIDAQABo2YwZDAOBgNVHQ8BAf8EBAMCAQYwEgYD
+VR0TAQH/BAgwBgEB/wIBAjAdBgNVHQ4EFgQUJOhTV118NECHqeuU27rhFnj8KaQw
+HwYDVR0jBBgwFoAUJOhTV118NECHqeuU27rhFnj8KaQwDQYJKoZIhvcNAQELBQAD
+ggEBAHwOf9Ur1l0Ar5vFE6PNrZWrDfQIMyEfdgSKofCdTckbqXNTiXdgbHs+TWoQ
+wAB0pfJDAHJDXOTCWRyTeXOseeOi5Btj5CnEuw3P0oXqdqevM1/+uWp0CM35zgZ8
+VD4aITxity0djzE6Qnx3Syzz+ZkoBgTnNum7d9A66/V636x4vTeqbZFBr9erJzgz
+hhurjcoacvRNhnjtDRM0dPeiCJ50CP3wEYuvUzDHUaowOsnLCjQIkWbR7Ni6KEIk
+MOz2U0OBSif3FTkhCgZWQKOOLo1P42jHC3ssUZAtVNXrCk3fw9/E15k8NPkBazZ6
+0iykLhH1trywrKRMVw67F44IE8Y=
+-----END CERTIFICATE-----
+-----BEGIN CERTIFICATE-----
+MIICiTCCAi6gAwIBAgIUXZP3MWb8MKwBE1Qbawsp1sfA/Y4wCgYIKoZIzj0EAwIw
+gY8xCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpDYWxpZm9ybmlhMRYwFAYDVQQHEw1T
+YW4gRnJhbmNpc2NvMRkwFwYDVQQKExBDbG91ZEZsYXJlLCBJbmMuMTgwNgYDVQQL
+Ey9DbG91ZEZsYXJlIE9yaWdpbiBTU0wgRUNDIENlcnRpZmljYXRlIEF1dGhvcml0
+eTAeFw0xOTA4MjMyMTA4MDBaFw0yOTA4MTUxNzAwMDBaMIGPMQswCQYDVQQGEwJV
+UzETMBEGA1UECBMKQ2FsaWZvcm5pYTEWMBQGA1UEBxMNU2FuIEZyYW5jaXNjbzEZ
+MBcGA1UEChMQQ2xvdWRGbGFyZSwgSW5jLjE4MDYGA1UECxMvQ2xvdWRGbGFyZSBP
+cmlnaW4gU1NMIEVDQyBDZXJ0aWZpY2F0ZSBBdXRob3JpdHkwWTATBgcqhkjOPQIB
+BggqhkjOPQMBBwNCAASR+sGALuaGshnUbcxKry+0LEXZ4NY6JUAtSeA6g87K3jaA
+xpIg9G50PokpfWkhbarLfpcZu0UAoYy2su0EhN7wo2YwZDAOBgNVHQ8BAf8EBAMC
+AQYwEgYDVR0TAQH/BAgwBgEB/wIBAjAdBgNVHQ4EFgQUhTBdOypw1O3VkmcH/es5
+tBoOOKcwHwYDVR0jBBgwFoAUhTBdOypw1O3VkmcH/es5tBoOOKcwCgYIKoZIzj0E
+AwIDSQAwRgIhAKilfntP2ILGZjwajktkBtXE1pB4Y/fjAfLkIRUzrI15AiEA5UCL
+XYZZ9m2c3fKwIenMMojL1eqydsgqj/wK4p5kagQ=
+-----END CERTIFICATE-----

firmware/main/frame_client.c

@@ -25,6 +25,27 @@ static const char *TAG = "frame_client";
 
 static EventGroupHandle_t s_sta_event_group;
 
+/* Cloudflare's Origin CA root certs (RSA + ECC, both concatenated --
+ * mbedtls_x509_crt_parse() chains every cert in a PEM buffer into the
+ * trust store, so either one nginx presents validates), for trusting an
+ * https tools server whose reverse proxy terminates TLS with a
+ * Cloudflare-issued origin certificate. See firmware/main/certs/. */
+extern const char cloudflare_origin_ca_pem_start[] asm("_binary_cloudflare_origin_ca_pem_start");
+
+/* Builds a full URL from cfg->toolsserver + a path (no leading slash).
+ * toolsserver is normally a bare "host:port", defaulting to plain http;
+ * it may instead carry an explicit "http://" or "https://" prefix to
+ * pick the scheme, e.g. "https://frame.example.com" if a reverse proxy
+ * is terminating TLS in front of the tools server. */
+static void build_url(char *out, size_t out_size, const char *toolsserver, const char *path)
+{
+    if (strncmp(toolsserver, "http://", 7) == 0 || strncmp(toolsserver, "https://", 8) == 0) {
+        snprintf(out, out_size, "%s/%s", toolsserver, path);
+    } else {
+        snprintf(out, out_size, "http://%s/%s", toolsserver, path);
+    }
+}
+
 /* wifi_sta_config_t's ssid/password fields are fixed-size byte arrays, not
  * necessarily null-terminated (a full 32-char SSID fills the field exactly).
  * snprintf() flags that as a possible truncation at -Werror, so copy by
@@ -200,12 +221,13 @@ static frame_server_config_t fetch_frame_config(const char *toolsserver)
     };
 
     char url[160];
-    snprintf(url, sizeof(url), "http://%s/frame/config", toolsserver);
+    build_url(url, sizeof(url), toolsserver, "frame/config");
 
     esp_http_client_config_t config = {
         .url = url,
         .method = HTTP_METHOD_GET,
         .timeout_ms = CONFIG_FRAME_SERVER_CHECK_TIMEOUT_MS,
+        .cert_pem = cloudflare_origin_ca_pem_start,
     };
     esp_http_client_handle_t client = esp_http_client_init(&config);
 
@@ -260,12 +282,13 @@ static void fetch_photo_info(const char *toolsserver, char *location_line1, size
     share_url[0] = '\0';
 
     char url[160];
-    snprintf(url, sizeof(url), "http://%s/frame/photo-info", toolsserver);
+    build_url(url, sizeof(url), toolsserver, "frame/photo-info");
 
     esp_http_client_config_t config = {
         .url = url,
         .method = HTTP_METHOD_GET,
         .timeout_ms = CONFIG_FRAME_SERVER_CHECK_TIMEOUT_MS,
+        .cert_pem = cloudflare_origin_ca_pem_start,
     };
     esp_http_client_handle_t client = esp_http_client_init(&config);
 
@@ -302,7 +325,9 @@ static void fetch_photo_info(const char *toolsserver, char *location_line1, size
 
     char asset_id[48];
     if (json_extract_string(body, "asset_id", asset_id, sizeof(asset_id))) {
-        snprintf(share_url, share_url_size, "http://%s/frame/share/%s", toolsserver, asset_id);
+        char path[80];
+        snprintf(path, sizeof(path), "frame/share/%s", asset_id);
+        build_url(share_url, share_url_size, toolsserver, path);
     }
 }
 
@@ -317,12 +342,13 @@ static void fetch_photo_info(const char *toolsserver, char *location_line1, size
 static int fetch_face_labels(const char *toolsserver, manage_face_label_t *out, int max_labels)
 {
     char url[160];
-    snprintf(url, sizeof(url), "http://%s/frame/face-labels", toolsserver);
+    build_url(url, sizeof(url), toolsserver, "frame/face-labels");
 
     esp_http_client_config_t config = {
         .url = url,
         .method = HTTP_METHOD_GET,
         .timeout_ms = CONFIG_FRAME_SERVER_CHECK_TIMEOUT_MS,
+        .cert_pem = cloudflare_origin_ca_pem_start,
     };
     esp_http_client_handle_t client = esp_http_client_init(&config);
 
@@ -456,12 +482,13 @@ static esp_err_t fetch_and_display(const frame_config_t *cfg, bool force_advance
                                     const manage_overlay_set_t *overlay)
 {
     char url[160];
-    snprintf(url, sizeof(url), "http://%s/%s", cfg->toolsserver, force_advance ? "frame/advance" : "frame/image");
+    build_url(url, sizeof(url), cfg->toolsserver, force_advance ? "frame/advance" : "frame/image");
 
     esp_http_client_config_t config = {
         .url = url,
         .method = force_advance ? HTTP_METHOD_POST : HTTP_METHOD_GET,
         .timeout_ms = CONFIG_FRAME_FETCH_TIMEOUT_MS,
+        .cert_pem = cloudflare_origin_ca_pem_start,
     };
     esp_http_client_handle_t client = esp_http_client_init(&config);
 
@@ -550,8 +577,14 @@ static bool wait_for_button_press(uint32_t timeout_ms)
  * photo, so it never re-advances. */
 static esp_err_t show_menu_level(const frame_config_t *cfg, bool force_advance, int level)
 {
-    char management_url[160];
-    snprintf(management_url, sizeof(management_url), "http://%s/", cfg->toolsserver);
+    char management_url[256];
+    build_url(management_url, sizeof(management_url), cfg->toolsserver, "");
+    if (cfg->access_token[0] != '\0') {
+        /* Embeds the token so scanning the QR just works -- matches the
+         * server's MANAGEMENT_TOKEN gate on GET / (see server/README.md). */
+        size_t len = strlen(management_url);
+        snprintf(management_url + len, sizeof(management_url) - len, "?token=%s", cfg->access_token);
+    }
 
     char location_line1[32];
     char location_line2[32];

firmware/main/root.html

@@ -90,7 +90,12 @@
 
             <div class="input-group">
                 <label for="toolsserver">Tools Server</label>
-                <input type="text" id="toolsserver" name="toolsserver" placeholder="e.g. 192.168.1.50:8080" required>
+                <input type="text" id="toolsserver" name="toolsserver" placeholder="e.g. 192.168.1.50:8080 or https://frame.example.com" required>
+            </div>
+
+            <div class="input-group">
+                <label for="access_token">Access Token (optional)</label>
+                <input type="text" id="access_token" name="access_token" placeholder="only if the server's MANAGEMENT_TOKEN is set">
             </div>
 
             <button type="submit">Submit</button>

firmware/main/wifi_provisioning.c

@@ -72,6 +72,16 @@ esp_err_t frame_config_load(frame_config_t *out)
         return pass_err;
     }
 
+    /* Also optional -- most deployments won't set a server-side
+     * MANAGEMENT_TOKEN at all, in which case this stays empty and the
+     * manage-menu QR just links to the page with no ?token=. */
+    len = sizeof(out->access_token);
+    esp_err_t token_err = nvs_get_str(handle, "access_token", out->access_token, &len);
+    if (token_err != ESP_OK && token_err != ESP_ERR_NVS_NOT_FOUND) {
+        nvs_close(handle);
+        return token_err;
+    }
+
     nvs_close(handle);
     return ESP_OK;
 }
@@ -91,6 +101,9 @@ esp_err_t frame_config_save(const frame_config_t *cfg)
     if (err == ESP_OK) {
         err = nvs_set_str(handle, "toolsserver", cfg->toolsserver);
     }
+    if (err == ESP_OK) {
+        err = nvs_set_str(handle, "access_token", cfg->access_token);
+    }
     if (err == ESP_OK) {
         /* Fresh (re)provisioning -- the next successful connection should
          * show the status screen again. */
@@ -139,6 +152,7 @@ void frame_config_clear(void)
     nvs_erase_key(handle, "sta_ssid");
     nvs_erase_key(handle, "sta_pass");
     nvs_erase_key(handle, "toolsserver");
+    nvs_erase_key(handle, "access_token");
     nvs_erase_key(handle, "connected_once");
     nvs_commit(handle);
     nvs_close(handle);
@@ -311,6 +325,7 @@ static esp_err_t save_config_post_handler(httpd_req_t *req)
     extract_form_value(body, "ssid", cfg.sta_ssid, sizeof(cfg.sta_ssid));
     extract_form_value(body, "password", cfg.sta_password, sizeof(cfg.sta_password));
     extract_form_value(body, "toolsserver", cfg.toolsserver, sizeof(cfg.toolsserver));
+    extract_form_value(body, "access_token", cfg.access_token, sizeof(cfg.access_token));
 
     if (strlen(cfg.sta_ssid) == 0 || strlen(cfg.toolsserver) == 0) {
         httpd_resp_send_err(req, HTTPD_400_BAD_REQUEST, "SSID and Tools Server are required");
@@ -324,7 +339,8 @@ static esp_err_t save_config_post_handler(httpd_req_t *req)
         return ESP_FAIL;
     }
 
-    ESP_LOGI(TAG, "Saved config: ssid='%s' toolsserver='%s'", cfg.sta_ssid, cfg.toolsserver);
+    ESP_LOGI(TAG, "Saved config: ssid='%s' toolsserver='%s' access_token=%s", cfg.sta_ssid, cfg.toolsserver,
+             strlen(cfg.access_token) ? "set" : "none");
 
     static const char resp[] =
         "<html><body><h3>Saved. Restarting and connecting to your WiFi...</h3></body></html>";

firmware/main/wifi_provisioning.h

@@ -7,12 +7,14 @@
 #define FRAME_CFG_SSID_MAX_LEN 32
 #define FRAME_CFG_PASSWORD_MAX_LEN 64
 #define FRAME_CFG_SERVER_MAX_LEN 128
+#define FRAME_CFG_TOKEN_MAX_LEN 64
 #define FRAME_AP_PASSWORD_LEN 10
 
 typedef struct {
     char sta_ssid[FRAME_CFG_SSID_MAX_LEN + 1];
     char sta_password[FRAME_CFG_PASSWORD_MAX_LEN + 1];
     char toolsserver[FRAME_CFG_SERVER_MAX_LEN + 1];
+    char access_token[FRAME_CFG_TOKEN_MAX_LEN + 1]; /* optional; matches the server's MANAGEMENT_TOKEN */
 } frame_config_t;
 
 /**