feat: authenticate the API via HTTP Basic Auth + document fork endpoints

Web_IsAuthenticated now also accepts the web password sent per-request via
HTTP Basic Auth (fixed username "espuino"), so API clients, scripts and the
Swagger UI can authenticate without the cookie/login flow (e.g.
'curl -u espuino:<pw>'). The existing session-cookie path is unchanged, and
with no web password set the API stays open.

Also fills the OpenAPI spec (REST-API.yaml, served at /swagger.html): adds all
fork-added endpoints (/sync, /syncstop, /playlist, /githubupdate, /version,
/login, /logout, /security, /eqrule(s), /activeequalizer, /bluetooth*,
/sdclean) and declares a basicAuth security scheme so 'Authorize' works.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: fhirschmann

README.md

@@ -115,7 +115,7 @@ neon logo that doubles as the SVG favicon ([`7be5254`](../../commit/7be5254)):
 | SD card cleanup: removes macOS metadata (`.DS_Store`, `._*`, Spotlight/Trashes) with one click | [`4e68541`](../../commit/4e68541) |
 | Live log: the log dialog refreshes every 2 s and follows the end of the log | [`5183e78`](../../commit/5183e78) |
 | Drag & drop: upload files by dropping them from the file manager onto the file tree | [`f8b477b`](../../commit/f8b477b) |
-| Password protection: single password (no username), 90-day session cookie, logout menu entry, brute-force lockout; inactive in hotspot mode | [`e74e712`](../../commit/e74e712) |
+| Password protection: single password (no username), 90-day session cookie, logout menu entry, brute-force lockout; inactive in hotspot mode. API clients/scripts can also authenticate per-request via **HTTP Basic Auth** (username `espuino`, password = the web password, e.g. `curl -u espuino:<pw>`) instead of the cookie/login flow | [`e74e712`](../../commit/e74e712) |
 | Log download as a text file | [`5d9d591`](../../commit/5d9d591) |
 | Battery indicator in the navbar with a low-battery warning toast | [`4566ae0`](../../commit/4566ae0) |
 | SD card capacity gauge in the files tab and the info dialog | [`45b340a`](../../commit/45b340a) |
@@ -135,6 +135,7 @@ neon logo that doubles as the SVG favicon ([`7be5254`](../../commit/7be5254)):
 | **HTTP file sync**: pull audio files from a web server (e.g. nginx) onto the SD card. A new **Sync** settings sub-tab takes a manifest URL plus optional HTTP Basic Auth (user/password); the device fetches a JSON manifest (`{"files":[{"path","size"},…]}`) and downloads every listed file that is missing locally or differs in size, streaming each in small chunks straight to SD. Additive only (never deletes), runs in a background task, and shows live progress including the file currently being downloaded plus a stop button to cancel a running sync. The **Sync** settings sub-tab holds the config (manifest URL + Basic Auth) and documents the manifest format/nginx setup; the actual run button and live progress live in the **Tools** tab, with a shortcut button in the Sync sub-tab that jumps there. If audio is playing when a sync starts, playback is paused for the SD-writing phase and resumes automatically when the sync finishes; pressing play (or skipping a track) cancels the running sync and resumes playback immediately | [`ac24bbc`](../../commit/ac24bbc) |
 | **Fully offline web interface**: all third-party libraries (jQuery, jQuery-UI, Bootstrap JS/CSS, jstree + themes, bootstrap-slider, Font Awesome + webfonts, i18next) and the Orbitron/Rajdhani/Share Tech Mono fonts are now vendored and served gzipped from the device instead of public CDNs. This fixes the ~2-minute first-load hang with empty (untranslated) text after a cold boot/flash, and makes the management UI work without any internet access (incl. AP mode). `processHtml.py` embeds the assets into flash (build size grows accordingly) and now derives unique header symbol names from the full asset path. The libs are concatenated into a single JS and a single CSS bundle (`tools/bundle_assets.py`) so the page makes only a handful of requests — many parallel requests to the ESP32's async web server made some browsers (Safari/Chrome) stall for minutes while Firefox coped | [`c618191`](../../commit/c618191) |
 | **M3U playlist builder**: a "Create playlist" button in the Files tab opens a two-pane builder — browse the SD card on the left, an ordered (drag-to-reorder) track list on the right — to assemble an `.m3u` from SD files, whole folders, and webradio URLs (which `LOCAL_M3U` plays interchangeably). Saving writes `/Playlists/<name>.m3u` via a new `POST /playlist` endpoint; the file can then be assigned to an RFID tag with play mode 11. i18n de/en/fr | [`af041fc`](../../commit/af041fc) |
+| **OpenAPI/Swagger spec updated**: the bundled `REST_API.yaml` (served at `/swagger.html`) now documents all fork-added endpoints (`/sync`, `/syncstop`, `/playlist`, `/githubupdate`, `/version`, `/login`, `/logout`, `/security`, `/eqrule(s)`, `/activeequalizer`, `/bluetooth*`, `/sdclean`) and declares a `basicAuth` security scheme so the Swagger "Authorize" button works (username `espuino`) | [`PENDING`](../../commit/PENDING) |
 
 #### Feature highlights
 

REST-API.yaml

@@ -12,6 +12,20 @@ servers:
     description: Local Device
   - url: "http://espuino.local/"
     description: Development ESPuino
+# When a web password is set, every endpoint (except /login and a few PWA assets)
+# requires authentication. Two equivalent ways to authenticate:
+#   * HTTP Basic Auth on each request — username "espuino", password = web password
+#     (e.g. `curl -u espuino:<password> ...`). Use the "Authorize" button in Swagger.
+#   * Cookie session — POST the password to /login, which sets the ESPUINO_SESSION cookie.
+# With no web password set, the API is open and authentication is ignored.
+components:
+  securitySchemes:
+    basicAuth:
+      type: http
+      scheme: basic
+      description: 'HTTP Basic Auth. Username is always "espuino"; password is the web-interface password.'
+security:
+  - basicAuth: []
 paths:
   /explorer:
     get:
@@ -581,3 +595,276 @@ paths:
       responses:
         "200":
           description: Successful response for initializing Hall Effect Sensor Value.
+  # ----------------------------------------------------------------------------
+  # Fork-specific endpoints (Leo Industries AT-1)
+  # ----------------------------------------------------------------------------
+  /sync:
+    get:
+      tags: [Fork]
+      summary: Get HTTP file-sync status.
+      description: Poll the progress/result of the HTTP(S) file sync.
+      responses:
+        "200":
+          description: Current sync state.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    type: integer
+                    description: "0=idle, 1=syncing, 2=done, 3=failed, 4=stopped"
+                  progress:
+                    type: integer
+                    description: Percent of files processed.
+                  message:
+                    type: string
+                    description: Current file (while syncing) or the result/error message.
+    post:
+      tags: [Fork]
+      summary: Start an HTTP file sync.
+      description: >-
+        Starts a background sync that pulls the files listed in the configured
+        manifest URL onto the SD card. No-op if a sync is already running. If
+        audio is playing it is paused for the SD-writing phase.
+      responses:
+        "200":
+          description: Sync started (or already running).
+  /syncstop:
+    post:
+      tags: [Fork]
+      summary: Stop the running file sync.
+      description: Requests a cooperative cancel of the currently running sync.
+      responses:
+        "200":
+          description: Stop requested.
+  /playlist:
+    post:
+      tags: [Fork]
+      summary: Create an .m3u playlist.
+      description: >-
+        Writes an .m3u playlist to the SD card from the given ordered list of
+        SD-file paths and/or webradio URLs (played interchangeably by LOCAL_M3U).
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [path, tracks]
+              properties:
+                path:
+                  type: string
+                  description: Target path; ".m3u" is appended if missing (e.g. /Playlists/mix).
+                tracks:
+                  type: array
+                  items:
+                    type: string
+                  description: Ordered track lines (SD paths or http(s) URLs).
+      responses:
+        "200":
+          description: Playlist created.
+        "400":
+          description: Missing path or tracks.
+        "500":
+          description: File could not be created.
+  /githubupdate:
+    get:
+      tags: [Fork]
+      summary: Get GitHub OTA status.
+      description: Poll the status of the GitHub firmware update.
+      responses:
+        "200":
+          description: Current update status.
+    post:
+      tags: [Fork]
+      summary: Start a GitHub OTA update.
+      description: Downloads the rolling "latest" firmware from GitHub over HTTPS and flashes it.
+      responses:
+        "200":
+          description: Update started.
+  /version:
+    get:
+      tags: [Fork]
+      summary: Get firmware version info.
+      description: Returns the running build/rolling version and whether an update is available.
+      responses:
+        "200":
+          description: Version info.
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: true
+  /security:
+    get:
+      tags: [Fork]
+      summary: Is web-interface password protection enabled?
+      responses:
+        "200":
+          description: Whether a web password is set.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  enabled:
+                    type: boolean
+    post:
+      tags: [Fork]
+      summary: Set or clear the web-interface password.
+      description: Sets a new web password (enables protection) or clears it when empty.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                password:
+                  type: string
+      responses:
+        "200":
+          description: Password updated.
+  /login:
+    post:
+      tags: [Fork]
+      summary: Log in to the web interface.
+      description: >-
+        Validates the password and sets the ESPUINO_SESSION cookie. Not needed
+        when authenticating per-request via HTTP Basic Auth (user "espuino").
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                password:
+                  type: string
+      responses:
+        "200":
+          description: Login successful; session cookie set.
+        "401":
+          description: Wrong password.
+        "429":
+          description: Temporarily locked after too many failed attempts.
+  /logout:
+    post:
+      tags: [Fork]
+      summary: Log out of the web interface.
+      description: Clears the ESPUINO_SESSION cookie.
+      responses:
+        "200":
+          description: Logged out.
+  /eqrules:
+    get:
+      tags: [Fork]
+      summary: List per-file/folder equalizer rules.
+      responses:
+        "200":
+          description: Equalizer rules.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  additionalProperties: true
+  /eqrule:
+    post:
+      tags: [Fork]
+      summary: Set a per-path equalizer rule.
+      parameters:
+        - in: query
+          name: path
+          required: true
+          schema:
+            type: string
+          description: SD path (file or folder) the rule applies to.
+        - in: query
+          name: low
+          schema:
+            type: integer
+        - in: query
+          name: band
+          schema:
+            type: integer
+        - in: query
+          name: high
+          schema:
+            type: integer
+        - in: query
+          name: profile
+          schema:
+            type: string
+          description: "Profile name (flat/music/speech/voiceBoost) or empty for custom bands."
+      responses:
+        "200":
+          description: Rule stored.
+    delete:
+      tags: [Fork]
+      summary: Delete a per-path equalizer rule.
+      parameters:
+        - in: query
+          name: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Rule deleted.
+  /activeequalizer:
+    get:
+      tags: [Fork]
+      summary: Get the active equalizer profile.
+      responses:
+        "200":
+          description: Active equalizer settings.
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: true
+  /bluetoothscan:
+    get:
+      tags: [Fork]
+      summary: Start a Bluetooth device scan.
+      responses:
+        "200":
+          description: Scan started.
+  /bluetoothresults:
+    get:
+      tags: [Fork]
+      summary: Get Bluetooth scan results.
+      responses:
+        "200":
+          description: Discovered devices.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: string
+  /bluetoothconnect:
+    post:
+      tags: [Fork]
+      summary: Connect to a Bluetooth device.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: true
+      responses:
+        "200":
+          description: Connect requested.
+  /sdclean:
+    post:
+      tags: [Fork]
+      summary: Clean the SD card cache.
+      description: Removes ESPuino's cached playlist/index files from the SD card.
+      responses:
+        "200":
+          description: Cleaned.

src/Web.cpp

@@ -452,10 +452,19 @@ static void Web_RefreshSessionToken(void) {
 	wwwSessionToken = Web_BuildSessionToken(password, salt);
 }
 
+// Fixed username for HTTP Basic Auth; only the password (the configured web password)
+// is checked. Lets API clients and the Swagger UI authenticate per-request via the
+// Authorization header (e.g. `curl -u espuino:<password>`) instead of the cookie flow.
+static constexpr const char *wwwBasicAuthUser = "espuino";
+
 static bool Web_IsAuthenticated(AsyncWebServerRequest *request) {
 	if (wwwSessionToken.length() == 0) {
 		return true;
 	}
+	// Accept the password sent directly via HTTP Basic Auth (username "espuino").
+	if (request->authenticate(wwwBasicAuthUser, gPrefsSettings.getString("wwwPassword", "").c_str())) {
+		return true;
+	}
 	if (!request->hasHeader("Cookie")) {
 		return false;
 	}