diff --git a/.github/workflows/ccpp.yml b/.github/workflows/ccpp.yml
index 84c9256300..39d73da791 100644
--- a/.github/workflows/ccpp.yml
+++ b/.github/workflows/ccpp.yml
@@ -64,6 +64,7 @@ env:
     -DBUILD_ALC=YES \
     -DBUILD_ALCC=YES \
     -DBUILD_AMULECMD=YES \
+    -DBUILD_AMULEAPI=YES \
     -DBUILD_CAS=YES \
     -DBUILD_DAEMON=YES \
     -DBUILD_WXCAS=YES \
diff --git a/LICENSE.md b/LICENSE.md
index 51ae63a89e..2485233f7e 100644
--- a/LICENSE.md
+++ b/LICENSE.md
@@ -1,3 +1,10 @@
+# aMule License
+
+aMule is released under the GNU General Public License, version 2 or
+later (the "GPLv2+"). The full text follows. Third-party components
+bundled into aMule's binary distributions retain their own permissive
+licenses, listed in [`docs/THIRDPARTY.md`](docs/THIRDPARTY.md).
+
 # GNU GENERAL PUBLIC LICENSE
 
 Version 2, June 1991
diff --git a/cmake/options.cmake b/cmake/options.cmake
index 248c7c70d1..f4ef2fa034 100644
--- a/cmake/options.cmake
+++ b/cmake/options.cmake
@@ -39,6 +39,7 @@ option (BUILD_FILEVIEW "compile aMule file viewer for console (EXPERIMENTAL)")
 option (BUILD_MONOLITHIC "enable building of the monolithic aMule app" ON)
 option (BUILD_REMOTEGUI "compile aMule remote GUI")
 option (BUILD_WEBSERVER "compile aMule WebServer")
+option (BUILD_AMULEAPI "compile aMule REST API daemon")
 option (BUILD_WXCAS "compile aMule GUI Statistics")
 option (BUILD_TESTING "Build unit tests" OFF)
 
@@ -63,6 +64,7 @@ if (BUILD_EVERYTHING)
 	set (BUILD_FILEVIEW ON CACHE BOOL "compile aMule file viewer for console (EXPERIMENTAL)" FORCE)
 	set (BUILD_REMOTEGUI ON CACHE BOOL "compile aMule remote GUI" FORCE)
 	set (BUILD_WEBSERVER ON CACHE BOOL "compile aMule WebServer" FORCE)
+	set (BUILD_AMULEAPI ON CACHE BOOL "compile aMule REST API daemon" FORCE)
 	set (BUILD_WXCAS ON CACHE BOOL "compile aMule GUI Statistics" FORCE)
 endif()
 
@@ -74,6 +76,39 @@ if (BUILD_AMULECMD)
 	set (NEED_ZLIB TRUE)
 endif()
 
+if (BUILD_AMULEAPI)
+	# Mirrors amulecmd's needs: EC connection, mulecommon helpers (Format,
+	# MD5Sum), socket lib for CRemoteConnect. Boost.Beast is header-only
+	# so we don't add a Boost component requirement; the link-side Boost
+	# is already wired via the project-level `Boost_LIBRARIES` lookup.
+	#
+	# Hard-fail policy. `BUILD_AMULEAPI=YES` + missing dep must fail
+	# at configure time, never soft-disable the target. Today the
+	# guarantees come from upstream wiring:
+	#   * cryptopp — `NEED_LIB_EC` (set below) implies `NEED_LIB_CRYPTO`,
+	#     which includes cmake/cryptopp.cmake; that file FATAL_ERRORs
+	#     on a missing `cryptlib.h`.
+	#   * Boost   — `cmake/boost.cmake` runs unconditionally at the
+	#     project root and uses `find_package(Boost CONFIG REQUIRED)`,
+	#     which FATAL_ERRORs on miss.
+	# If a future refactor breaks either chain (e.g. moves Boost
+	# behind a conditional `if`), add an explicit `find_package(Boost
+	# CONFIG REQUIRED)` here so amuleapi keeps fail-loud.
+	set (NEED_LIB_EC TRUE)
+	set (NEED_LIB_MULECOMMON TRUE)
+	set (NEED_LIB_MULESOCKET TRUE)
+	set (wx_NEED_NET TRUE)
+	set (NEED_ZLIB TRUE)
+	# Compile-time install path the daemon falls back to when
+	# [Server]/StaticRoot is empty in the conf. Mirrors WEBSERVERDIR but
+	# uses the ABSOLUTE form so a binary running from /usr/local/bin
+	# (or wherever the operator put it) resolves to the matching
+	# /usr/local/share/amule/amuleapi-static without needing to be
+	# cwd'd at the install prefix.
+	set (AMULEAPI_STATIC_DIR
+		"${CMAKE_INSTALL_FULL_DATADIR}/${PACKAGE}/amuleapi-static/")
+endif()
+
 if (BUILD_CAS)
 	set (BUILD_UTIL TRUE)
 endif()
@@ -196,7 +231,7 @@ endif()
 # wxWidgets::NET directly in src/webserver/src/CMakeLists.txt for its
 # socket code). Keep wx_NEED_NET on only when those are actually being
 # built.
-if (NOT (BUILD_DAEMON OR BUILD_MONOLITHIC OR BUILD_REMOTEGUI OR BUILD_WEBSERVER OR BUILD_WXCAS OR BUILD_AMULECMD))
+if (NOT (BUILD_DAEMON OR BUILD_MONOLITHIC OR BUILD_REMOTEGUI OR BUILD_WEBSERVER OR BUILD_WXCAS OR BUILD_AMULECMD OR BUILD_AMULEAPI))
 	set (wx_NEED_NET FALSE)
 endif()
 
diff --git a/config.h.cm b/config.h.cm
index 6986aab31f..7e73f2eb19 100644
--- a/config.h.cm
+++ b/config.h.cm
@@ -189,6 +189,10 @@
 /* Where the webserver finds it's themes */
 #cmakedefine WEBSERVERDIR "${WEBSERVERDIR}"
 
+/* Compile-time install path of amuleapi's bundled static frontend.
+   amuleapi falls back to this when [Server]/StaticRoot is empty. */
+#cmakedefine AMULEAPI_STATIC_DIR "${AMULEAPI_STATIC_DIR}"
+
 /* Define if libpng is present is set. */
 #cmakedefine WITH_LIBPNG
 
diff --git a/docs/INSTALL.md b/docs/INSTALL.md
index a71caf3f64..788355f798 100644
--- a/docs/INSTALL.md
+++ b/docs/INSTALL.md
@@ -128,6 +128,7 @@ Common `-D` options (`YES` / `NO` unless noted otherwise):
 | `BUILD_DAEMON`           | NO      | `amuled` — headless daemon                                               |
 | `BUILD_AMULECMD`         | NO      | `amulecmd` — CLI client for the daemon                                   |
 | `BUILD_WEBSERVER`        | NO      | `amuleweb` — HTTP interface for the daemon                               |
+| `BUILD_AMULEAPI`         | NO      | `amuleapi` — REST API + SSE daemon ([docs/QUICKSTART-AMULEAPI.md](QUICKSTART-AMULEAPI.md)) |
 | `BUILD_ED2K`             | NO      | `ed2k` — handle `ed2k://` links                                          |
 | `BUILD_CAS`              | NO      | `cas` — C statistics tool                                                |
 | `BUILD_WXCAS`            | NO      | `wxCas` — GUI statistics tool                                            |
diff --git a/docs/QUICKSTART-AMULEAPI.md b/docs/QUICKSTART-AMULEAPI.md
new file mode 100644
index 0000000000..e9887673e6
--- /dev/null
+++ b/docs/QUICKSTART-AMULEAPI.md
@@ -0,0 +1,245 @@
+# amuleapi — quick start
+
+amuleapi is a standalone HTTP daemon that serves a versioned JSON REST API
+and a long-lived Server-Sent Events stream backed by amuled. It connects
+to amuled as an EC client (same protocol amuleweb and amulecmd use) and
+exposes its own HTTP surface on a separate port. amuleapi is the first
+shipping REST API for aMule — there is no prior on-the-wire surface to
+migrate from.
+
+For the endpoint list see the [What ships](#what-ships) section below. Full per-endpoint contracts (methods, query params, request bodies, response shapes, error codes) live in [`docs/api/REFERENCE.md`](api/REFERENCE.md); the SSE event catalog and Last-Event-ID reconnect semantics live in [`docs/api/EVENTS.md`](api/EVENTS.md). The source of truth for routing is [`src/webapi/Api.cpp`](../src/webapi/Api.cpp).
+
+## Requirements
+
+- A running `amuled` (or a monolithic `aMule` with EC enabled) that
+  amuleapi can connect to over the EC protocol.
+- The EC password from `amule.conf[ExternalConnect]/Password` (set via
+  `amuled --ec-config` if you've never run it).
+
+## First-run setup
+
+amuleapi keeps its config in the same per-platform aMule data directory
+that `amuled` uses.
+
+> **Cohabitation with amuled.** This is the same directory amuled
+> keeps `amule.conf` and `*.met` in — intentionally so. amuleapi's
+> three files (`amuleapi.conf`, `amuleapi-jwt-secret`,
+> `amuleapi-passwords`) sit alongside amuled's without colliding,
+> and operators reading both sets of configs together don't have
+> to context-switch directories. amuleapi never touches amuled's
+> files; amuled never touches amuleapi's.
+
+The default location:
+
+| Platform | Default config dir                                  |
+| -------- | --------------------------------------------------- |
+| Linux    | `~/.aMule/`                                         |
+| macOS    | `~/Library/Application Support/aMule/`              |
+| Windows  | `%APPDATA%\aMule\`                                  |
+
+Override with `amuleapi --config-dir=/path/to/dir`.
+
+The directory holds three amuleapi-specific files, all written with mode
+`0600`:
+
+| File                      | Purpose                                                                                                  |
+| ------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `amuleapi.conf`           | INI-style runtime config (HTTP bind/port/CORS, outbound EC connection to amuled, login rate-limit knobs, SSE event-bus ring size). Full reference below. |
+| `amuleapi-jwt-secret`     | 32-byte HMAC signing key for issued tokens. Auto-generated on first launch if absent.                    |
+| `amuleapi-passwords`      | MD5-hashed admin and guest passwords. Plaintext is never persisted.                                      |
+
+Set passwords via the dedicated CLI flags. Each invocation writes the
+file and exits — the HTTP server is NOT brought up, no EC connection
+is attempted, and the exit code reflects success / failure (so
+`amuleapi --set-admin-pass=... && systemctl restart amuleapi` actually
+short-circuits if the write fails):
+
+```sh
+amuleapi --set-admin-pass=mySecret123
+amuleapi --set-guest-pass=readOnlyPass
+```
+
+An empty password row means "this role is disabled" and
+`POST /api/v0/auth/login` returns `login_disabled` for that role.
+
+## Running
+
+```sh
+amuleapi --host=127.0.0.1 --port=4712 --password=$EC_PASSWORD
+```
+
+> **Two ports.** `--port=4712` is the EC port amuleapi USES to talk
+> to amuled (i.e. it's a client of amuled on 4712). amuleapi's OWN
+> HTTP listener is on `amuleapi.conf[Server]/Port` (default 4713)
+> — that's the port REST clients hit. The example above starts a
+> daemon that consumes 4712 (outbound to amuled) and serves 4713
+> (inbound from REST clients).
+
+- `--host` / `--port` / `--password` specify the EC connection to
+  `amuled` (default port `4712`).
+- HTTP serves on `amuleapi.conf[Server]/Port` (default `4713`).
+- amuleweb can run concurrently on its own port (default `4711`); the
+  two daemons talk to amuled independently as separate EC clients.
+
+aMule does not ship init-system units (systemd, launchd, Windows
+service) for any of its daemons. If you want one, write a downstream
+unit that wraps the command above.
+
+## Verifying
+
+```sh
+# Public — no auth.
+curl -s http://127.0.0.1:4713/api/v0/version
+
+# Login → token.
+# `?type=bearer` opts into the SDK-client response shape: the JWT
+# lands in the JSON body so a shell script can extract it. Browser
+# clients call /auth/login WITHOUT ?type=bearer and authenticate via
+# the HttpOnly session cookie set on the response — that's the
+# default to keep the token out of any XSS-readable surface.
+TOKEN=$(curl -s -X POST "http://127.0.0.1:4713/api/v0/auth/login?type=bearer" \
+    -H 'Content-Type: application/json' \
+    -d '{"password":"mySecret123"}' | jq -r .token)
+
+# Authenticated GETs.
+curl -s -H "Authorization: Bearer $TOKEN" \
+    http://127.0.0.1:4713/api/v0/status
+
+# Live event stream — open in a separate terminal and trigger
+# mutations elsewhere to watch events flow.
+curl -s -N -H "Authorization: Bearer $TOKEN" \
+    http://127.0.0.1:4713/api/v0/events
+```
+
+## `amuleapi.conf` reference
+
+INI-style file written with mode `0600`. The defaults file is created on first launch if absent — edits roundtrip through `wxFileConfig`, so quotes and comments are preserved across daemon restarts. The full surface:
+
+```ini
+[Server]
+BindAddress=127.0.0.1
+Port=4713
+AllowCORS=0
+CorsOriginAllowlist=
+StaticRoot=
+
+[EC]
+Host=127.0.0.1
+Port=4712
+Password=
+
+[Auth]
+LoginFailureWindowSeconds=60
+LoginFailureThreshold=5
+LoginLockoutSeconds=300
+
+[Streaming]
+EventBusRingCapacity=16384
+```
+
+### `[Server]` — HTTP listener
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `BindAddress` | `127.0.0.1` | Interface the HTTP listener binds to. Non-loopback binds are rejected at startup unless at least one of admin/guest passwords is set (the "publicly listening with no password" footgun gate in `App.cpp`). Overridable with `--bind=…` on the CLI. |
+| `Port` | `4713` | TCP port for inbound REST traffic. Distinct from amuled's EC port (`[EC]/Port`, default 4712). Overridable with `--http-port=…`. |
+| `AllowCORS` | `0` | `1` enables CORS headers (`Access-Control-Allow-Origin`, `Access-Control-Allow-Credentials: true`, `Vary: Origin`, preflight OPTIONS). Required for browser clients hosted on a different origin. See §CORS below. |
+| `CorsOriginAllowlist` | *(empty)* | Comma-separated list of origins that may set credentialed CORS requests. Empty + `AllowCORS=1` echoes the caller's `Origin` verbatim (wildcard-equivalent that remains cookie-compatible). |
+| `StaticRoot` | *(empty)* | Absolute filesystem path of a bundled web frontend. Empty (default) auto-discovers the bundled placeholder via the install-path chain (`make install` target on Linux/Windows, `aMule.app/Contents/Resources/amuleapi-static` on macOS) — same pattern amuleweb uses for templates, see [`WebInterface.cpp:146`](../src/webserver/src/WebInterface.cpp#L146). If no install is found, the daemon stays API-only and non-`/api/` paths return `404`. A non-empty `StaticRoot` overrides discovery and serves `GET`/`HEAD` requests outside `/api/` from that directory, with `index.html` SPA fallback for extension-less misses. Reads are containment-checked (symlinks pointing outside the root are rejected on POSIX; lexical `..`-rejection on Windows where symlinks require elevation), capped at 16 MiB per asset, and emit a mtime-size `ETag` so subsequent loads short-circuit to `304` via `If-None-Match`. |
+
+### `[EC]` — outbound connection to amuled
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `Host` | `127.0.0.1` | Hostname or IP of the running amuled daemon. amuleapi is a long-lived EC client; CLI `--host=…` overrides. |
+| `Port` | `4712` | amuled's EC listener port (matches amuled's `[ExternalConn]/ECPort`). CLI `--port=…` overrides. |
+| `Password` | *(empty)* | Plaintext EC password matching amuled's `[ExternalConn]/ECPassword`. Stored cleartext because the base class wants a hashable plaintext — the `0600` file mode matches `amuleapi-jwt-secret` and `amuleapi-passwords`. CLI `--password=…` overrides. |
+
+### `[Auth]` — login rate limiter
+
+Drives the `/auth/login` per-IP throttle (`CRateLimiter` in `Auth.cpp`). Failures inside the sliding window count toward the threshold; tripping it locks the offending IP out for `LoginLockoutSeconds`. Successful logins reset the bucket immediately.
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `LoginFailureWindowSeconds` | `60` | Sliding window in seconds. Failures older than this fall off the count. |
+| `LoginFailureThreshold` | `5` | Failures within the window before the IP is locked out. |
+| `LoginLockoutSeconds` | `300` | Duration of the IP lockout once tripped. While locked, `/auth/login` returns `429 rate_limited` with a `Retry-After` header. |
+
+### `[Streaming]` — SSE event bus
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `EventBusRingCapacity` | `16384` | Number of events the in-memory SSE bus retains for `Last-Event-ID` replay. Sized to absorb a cold-start tick on a busy node (5 K downloads + 5 K shared can publish ~10 K `*_added` events in a single tick). Worst-case memory ≈ capacity × ~1 KB JSON payload. Values below the bus's compile-time floor (16) are clamped up. Raise this on operator-heavy nodes where reconnecting clients are hitting `resync` events from natural traffic; lower it (e.g. `32`) only for the smoke-test gap-path scenario. |
+
+CLI `--bind`, `--http-port`, `--host`, `--port`, `--password`, and `--config-dir` override the matching keys at runtime without rewriting the file.
+
+## CORS
+
+By default amuleapi serves no CORS headers (same-origin only). To allow
+cross-origin browser clients, set in `amuleapi.conf`:
+
+```ini
+[Server]
+AllowCORS=1
+CorsOriginAllowlist=https://your-app.example.com,https://staging.example.com
+```
+
+Leave `CorsOriginAllowlist` empty to echo any caller's `Origin` header
+(wildcard-equivalent that stays cookie-compatible).
+
+> **CORS note.** The empty-allowlist form is *not* literally
+> `Access-Control-Allow-Origin: *`. amuleapi echoes the caller's
+> exact `Origin` value, which is the only shape browsers accept
+> together with `Access-Control-Allow-Credentials: true` (RFC 6454
+> + Fetch spec). A literal `*` would refuse cookie auth on cross-
+> origin requests — which is what every browser session relies on.
+
+## What ships
+
+- `/api/v0/auth/login` / `logout` / `session` — JWT and session-cookie auth
+- `/api/v0/version`, `/status`, `/preferences`
+- `/api/v0/downloads`, `/shared`, `/servers`, `/kad`,
+  `/clients` (the per-peer view, with optional
+  `?filter=uploads|downloads|active` for the legacy "Uploads" page
+  subset), `/categories`, `/logs/{amule,serverinfo}`,
+  `/stats/{tree,graphs/{graph}}`, `/search`, `/search/results`
+- POST / PATCH / DELETE mutations on each resource (admin role)
+- ETag-on-GET conditional caching (304 Not Modified on `If-None-Match`)
+- `/api/v0/events` — long-lived Server-Sent Events stream with
+  `Last-Event-ID` replay and typed `resync` events for cache invalidation
+- Every runtime tunable lives in `amuleapi.conf`; see the §`amuleapi.conf` reference above for sections, keys, and defaults.
+
+## Notes on a few responses
+
+- **`POST /api/v0/downloads` partial success.** The endpoint accepts
+  a single `ed2k_link` or an array of `links`. When some links land
+  cleanly and others fail (already on queue, malformed magnet,
+  category out of range, or EC disconnect mid-batch) the response is
+  `207 Multi-Status` with `ok: false` and four parallel arrays —
+  `accepted_links`, `failed_links`, `disconnected_links`, plus
+  counters and a `first_error`. `207` is borrowed from WebDAV (RFC
+  4918 §13) for "the request was answered in pieces"; clients should
+  treat it as success-with-details, not as a 4xx. `503` is reserved
+  for "every link blocked by an EC disconnect" — nothing landed and
+  the caller can retry once `GET /status` reports `ec_connected:
+  true`.
+
+## Security notes
+
+- The admin role grants the holder full control of the daemon's
+  network surface — that includes `POST /api/v0/servers/update
+  {"servers_url": "..."}`, which makes amuled fetch the supplied URL
+  to refresh the server list. This is the same behaviour amuled has
+  exposed via the desktop GUI and amuleweb for years, but it widens
+  what an admin token *grants* — anyone who steals one can ask
+  amuled to perform an HTTP GET against arbitrary network-reachable
+  URLs (a classic SSRF surface) and bring the response back into
+  amuled's process. The `http://` / `https://` pre-check in the API
+  is hygienic input validation, not a security boundary; protect
+  the admin password and the JWT signing secret accordingly.
+- The default `BindAddress=127.0.0.1` is load-bearing. The HTTP
+  server spawns one OS thread per Server-Sent Events subscriber, so
+  binding amuleapi to a non-loopback interface exposes the
+  thread-per-connection model to unauthenticated peers. If you need
+  remote access, put a reverse proxy in front and keep the bind on
+  loopback.
diff --git a/docs/THIRDPARTY.md b/docs/THIRDPARTY.md
new file mode 100644
index 0000000000..79070fdb88
--- /dev/null
+++ b/docs/THIRDPARTY.md
@@ -0,0 +1,60 @@
+# Third-party components
+
+aMule binary distributions (AppImage, Flatpak, .deb, macOS bundle, Windows
+installer) include code from third parties under their own permissive
+licenses. This file reproduces the copyright notice and license terms for
+each, as required by their respective binary-distribution clauses. aMule's
+own code is under GPLv2-or-later — see [LICENSE.md](../LICENSE.md).
+
+## picojson
+
+JSON parser used by `libwebcommon` (the REST API + SSE auth surface
+shared by amuleapi). License: BSD 2-Clause Simplified.
+
+Upstream: <https://github.com/kazuho/picojson> — version 1.3.0,
+vendored at [`src/libwebcommon/picojson.h`](../src/libwebcommon/picojson.h).
+Full license text in
+[`src/libwebcommon/picojson.LICENSE`](../src/libwebcommon/picojson.LICENSE).
+
+> Copyright 2009-2010 Cybozu Labs, Inc.
+> Copyright 2011-2014 Kazuho Oku
+> All rights reserved.
+>
+> Redistribution and use in source and binary forms, with or without
+> modification, are permitted provided that the following conditions are met:
+>
+> 1. Redistributions of source code must retain the above copyright notice,
+>    this list of conditions and the following disclaimer.
+>
+> 2. Redistributions in binary form must reproduce the above copyright notice,
+>    this list of conditions and the following disclaimer in the documentation
+>    and/or other materials provided with the distribution.
+>
+> THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+> AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+> IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+> ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+> LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+> CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+> SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+> INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+> CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+> ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+> POSSIBILITY OF SUCH DAMAGE.
+
+The vendored header is unmodified upstream 1.3.0; the
+`PICOJSON_USE_INT64` toggle is defined at use sites rather than as a
+modification to the header.
+
+## muleunit
+
+Lightweight unit test framework used by the C++ test suite at
+`unittests/tests/`. License: GNU LGPL v2.1.
+
+Source ships at [`unittests/muleunit/`](../unittests/muleunit/); full
+license text in
+[`unittests/muleunit/license.txt`](../unittests/muleunit/license.txt).
+The framework is statically linked into every test binary but is NOT
+linked into shipped daemon binaries (`amule`, `amuled`, `amulegui`,
+`amuleweb`, `amuleapi`), so the LGPL relinking clause does not constrain
+end-user binary distribution.
diff --git a/docs/api/EVENTS.md b/docs/api/EVENTS.md
new file mode 100644
index 0000000000..a4097115ee
--- /dev/null
+++ b/docs/api/EVENTS.md
@@ -0,0 +1,445 @@
+# amuleapi v0 — Server-Sent Events
+
+This document is the contract for the `/api/v0/events` Server-Sent Events stream. For the REST surface see [REFERENCE.md](REFERENCE.md). For first-run setup see [../QUICKSTART-AMULEAPI.md](../QUICKSTART-AMULEAPI.md).
+
+## Why SSE
+
+Polling `/api/v0/downloads` every second for a few thousand transfers is a multi-MB-per-tick conversation that the ETag cache helps with but can't eliminate — even a 304 still costs the round trip. SSE lets the daemon push only the deltas the client hasn't seen: a single `download_updated` per transfer per second, against a JSON envelope of a few hundred bytes.
+
+Clients connect once, leave the connection open, and react to typed events as they arrive. The browser EventSource API and `curl -N` both work out of the box.
+
+## Bootstrap: snapshot + stream
+
+REST snapshots and the `/events` stream need a specific call ordering or events that fire between them are silently lost. The right sequence:
+
+1. **Open `/api/v0/events` first** — buffer arrivals, don't apply yet. No `Last-Event-ID` is fine; the cursor anchors on whatever id was newest at handshake time.
+2. **`GET` the REST collections** in parallel.
+3. **Load, drain, flip** — load each snapshot into the store, drain the buffer in arrival order, then switch to direct-apply, all in one synchronous turn so no event can land between drain and flip.
+
+Buffer-then-replay (rather than merging the snapshot into a live store) is required because of `_removed` events: a snapshot built before the refresher's exclusive lock for a removing tick can still contain the deleted entity, and a merge-style load would `set()` it back over a buffered delete. With buffer-then-replay the snapshot lands first, the buffered `_removed` then clears the stale entry.
+
+```js
+// 1. Open SSE first. One dispatcher per event type, behaviour switched
+//    by a boot flag so we don't have to add-then-remove listeners.
+let booting = true;
+const buffered = [];
+
+function onEvent(ev) {
+  const entry = { type: ev.type, data: JSON.parse(ev.data) };
+  if (booting) buffered.push(entry);
+  else applyEvent(entry);
+}
+
+const EVENT_TYPES = [
+  "download_added", "download_updated", "download_removed",
+  "shared_added",   "shared_updated",   "shared_removed",
+  "client_added",   "client_updated",   "client_removed",
+  "server_added",   "server_updated",   "server_removed",
+  "status_changed", "log_appended",
+  "search_result_added", "search_progress",
+];
+const es = new EventSource("/api/v0/events", { withCredentials: true });
+for (const t of EVENT_TYPES) es.addEventListener(t, onEvent);
+es.addEventListener("resync", () => location.reload()); // simplest recovery
+
+// 2. Pull baseline snapshots in parallel.
+const [downloads, shared, clients, servers, status] = await Promise.all([
+  fetch("/api/v0/downloads").then((r) => r.json()),
+  fetch("/api/v0/shared").then((r) => r.json()),
+  fetch("/api/v0/clients").then((r) => r.json()),
+  fetch("/api/v0/servers").then((r) => r.json()),
+  fetch("/api/v0/status").then((r) => r.json()),
+]);
+
+// 3. Load each snapshot into the store, drain the buffer, flip the flag —
+//    single synchronous block so no event can fire between drain and flip.
+//    `loadSnapshot` is your store-specific "replace this collection" call,
+//    e.g. `store.set(name, payload)` or `collections.set(name, new Map(...))`.
+loadSnapshot("downloads", downloads);
+loadSnapshot("shared",    shared);
+loadSnapshot("clients",   clients);
+loadSnapshot("servers",   servers);
+loadSnapshot("status",    status);
+for (const ev of buffered) applyEvent(ev);
+buffered.length = 0;
+booting = false;
+```
+
+If the daemon restarts between steps 1 and 2, or the ring buffer overflows on a very busy bus, the synthetic `resync` event tells the client to wipe its cache and re-GET. See [Reconnect and Last-Event-ID](#reconnect-and-last-event-id) for the recovery rules — the bootstrap path is the same `GET` sweep, just on a non-fresh cache.
+
+## Connecting
+
+`GET /api/v0/events` opens the stream. Auth runs synchronously BEFORE the worker thread is spawned and before the 32-slot streaming budget is touched, so an unauthenticated peer can't tie up a slot for the read-timeout window.
+
+```sh
+TOKEN=$(curl -s -X POST -H "Content-Type: application/json" \
+  -d '{"password":"adminpass"}' \
+  "http://$HOST/api/v0/auth/login?type=bearer" | jq -r .token)
+
+curl -N -H "Authorization: Bearer $TOKEN" http://$HOST/api/v0/events
+```
+
+Browser:
+
+```js
+const es = new EventSource("/api/v0/events", { withCredentials: true });
+es.addEventListener("download_added",   (e) => { /* JSON.parse(e.data) */ });
+es.addEventListener("download_updated", (e) => { /* ... */ });
+es.addEventListener("download_removed", (e) => { /* ... */ });
+es.addEventListener("resync",           (e) => { /* re-GET REST collections */ });
+es.addEventListener("error",            ()  => {
+  // EventSource auto-reconnects with backoff; only surface to UI on terminal failure.
+  if (es.readyState === EventSource.CLOSED) { /* show "disconnected" */ }
+});
+```
+
+The cookie-based auth path is the default for browser EventSource — the HttpOnly cookie set by `/auth/login` is carried automatically. Bearer-auth works for `curl -N` and any HTTP client that lets you set request headers, but the native browser `EventSource` API doesn't, so browser bearer-on-SSE needs a polyfill (e.g. [`@microsoft/fetch-event-source`](https://github.com/Azure/fetch-event-source)). For browser SPAs the cookie path is the friction-free choice.
+
+### Auth failure shape
+
+Auth failures land on the SSE endpoint with the same JSON error envelope as the REST surface, not as an event frame. The HTTP status reflects the failure (`401`, `403`, `429`) so well-behaved clients can react before the stream loop starts. Example:
+
+```
+HTTP/1.1 401 Unauthorized
+Content-Type: application/json
+
+{"error":{"code":"unauthorized","message":"missing bearer token or session cookie"}}
+```
+
+### Response headers
+
+```
+HTTP/1.1 200 OK
+Content-Type: text/event-stream
+Cache-Control: no-cache
+X-Accel-Buffering: no
+Connection: keep-alive
+```
+
+`X-Accel-Buffering: no` tells nginx (the most common reverse proxy in front of amuleapi) not to coalesce chunks — without it, the stream stalls until the proxy buffer fills.
+
+### Initial chunk
+
+The first thing the client sees is a comment line:
+
+```
+: connected
+
+```
+
+Comment lines start with `:` and are discarded by SSE parsers. They keep the channel observably alive for browsers whose `onopen` fires only after a real chunk lands.
+
+## Frame format
+
+Every event the daemon emits has the same three-line shape:
+
+```
+event: <name>
+id: <id>
+data: <json>
+
+```
+
+The trailing blank line terminates the frame. `id` is a monotonically increasing `uint64` per amuleapi process — see [Reconnect and Last-Event-ID](#reconnect-and-last-event-id) below. `data` is the JSON payload documented per event in [Event catalog](#event-catalog). Payloads never contain literal newlines (the diff serializer escapes them) so one `data:` line is always enough.
+
+## Channels and filtering
+
+Every event belongs to a single channel. The full set, prefix-mapped from the event name:
+
+| Channel | Event-name prefix | What changed |
+|---------|-------------------|--------------|
+| `downloads` | `download_*` | Transfers in the active queue |
+| `shared` | `shared_*` | Shared file list |
+| `servers` | `server_*` | Known ed2k servers |
+| `clients` | `client_*` | Peers we're exchanging with |
+| `status` | `status_*` | Connection state + headline counters |
+| `logs` | `log_*` | amuled log buffer (live tail; serverinfo is poll-only) |
+| `search` | `search_*` | Result deltas + completion of an active `POST /search` |
+
+By default every channel is delivered. To subscribe to a subset, pass `?channels=` with a comma-separated list:
+
+```sh
+curl -N -H "Authorization: Bearer $TOKEN" \
+  "http://$HOST/api/v0/events?channels=downloads,status"
+```
+
+Unknown channel names in the query are silently ignored — forward-compatibility hedge for future event families. The token cap on the filter set is 32 to bound the memory the parser allocates; passing more is silently truncated.
+
+The synthetic `resync` event (see below) is ALWAYS delivered regardless of the filter. Its purpose is to signal a cache invalidation that the client cannot opt out of.
+
+Mirror your filter in the bootstrap: only `GET` the REST collections matching the channels you subscribed to. Pulling a collection whose channel you filtered out leaves that snapshot silently stale — it never receives updates from the stream.
+
+## Heartbeat
+
+If 15 seconds pass with no event written to the wire, the daemon emits:
+
+```
+: keepalive
+
+```
+
+NAT / load balancers / browser EventSource implementations tend to drop idle TCP connections after 30–60 s of silence. The heartbeat keeps the connection warm. The interval is wall-clock-driven (not Drain-timeout-driven) so a busy bus paired with a restrictive `?channels=` filter — where each Drain returns immediately because events are pending but all of them get filtered out — still emits keepalives on schedule.
+
+## Reconnect and Last-Event-ID
+
+EventSource clients (and well-behaved SDK clients) handle the underlying socket dropping by reopening the stream and replaying the `id:` of the last event they processed via the `Last-Event-ID` request header. The daemon's reconnect path uses that to figure out what (if anything) it can resume:
+
+| Scenario | Daemon response | What the client sees |
+|----------|-----------------|----------------------|
+| Header absent or unparseable | Start at the current newest id | New events as they arrive — no replay |
+| `parsed_id + 1 >= OldestId` | Resume from `parsed_id` | First Drain returns the missed range immediately |
+| `parsed_id + 1 < OldestId` (gap) | Emit a synthetic `resync` event with `reason: "gap"`, start at current newest | Client invalidates its cache and re-GETs the REST collections |
+| `parsed_id > NewestId` (stale) | Emit a synthetic `resync` event with `reason: "restart"`, start at current newest | Client invalidates: amuleapi was restarted (ids are per-process and reset to 1 on each launch) |
+
+The ring buffer holds 16 384 events by default — sized to absorb a cold-start tick on a busy node (5 K downloads + 5 K shared can publish ~10 K `*_added` events in a single tick before any subscriber has had a chance to drain). Operators with very heavy workloads can raise the cap via `amuleapi.conf[Streaming]/EventBusRingCapacity`; values below the bus's compile-time floor (16) are clamped up so an operator can't accidentally disable replay. Worst-case memory ≈ capacity × ~1 KB JSON payload. A burst that adds more events than capacity between reconnects triggers the "gap" path.
+
+The same gap detection also runs on the live path: if a publisher floods the bus between two `Drain()` calls and evicts events the current subscriber hadn't seen, the daemon emits the same `resync` frame and restarts the subscriber's cursor at the current newest. This catches the cold-start tick described above when capacity is set lower than the burst size.
+
+### `resync` frame
+
+```
+event: resync
+id: <current newest>
+data: {"reason":"gap","since_id":<old cursor>,"newest_id":<new cursor>}
+
+```
+
+`reason` is `"gap"` (events evicted from the ring before the subscriber read them) or `"restart"` (subscriber's id was past the bus's newest — only possible after a daemon restart). On either, the client's correct response is:
+
+1. Wipe its in-memory cache of whatever REST collections it tracked.
+2. Re-GET those collections from the REST surface.
+3. Continue accepting events from the new id.
+
+Both `since_id` and `newest_id` are uint64. The client never has to compute them — it should treat them as opaque and use `id:` on subsequent events.
+
+## Event catalog
+
+Every event the bus publishes. The `_added` and `_updated` payloads are BYTE-FOR-BYTE identical to the matching REST resource's list-item shape — clients receiving a `*_updated` event get the full new state and never need to re-GET. `_removed` carries only the identity field — `hash` for files (`download_removed`, `shared_removed`), `client_ecid` for `client_removed`, `ecid` for `server_removed` — so the client can drop the cache entry without needing the old object. Two events don't fit the collection-delta model: `status_changed` ships a full status envelope (replace, not merge) and `log_appended` is an append operation (`{lines}` — push the lines onto the amule log buffer, don't replace). Branch on the event type in your dispatcher accordingly.
+
+### `downloads` channel
+
+#### `download_added` / `download_updated`
+
+Identical to the REST [`/api/v0/downloads`](REFERENCE.md#get-apiv0downloads) list-item shape. `_updated` fires on any field-level change including `size_done`, `size_xfer`, `speed_bps`, and the source counters — clients see live progress without polling.
+
+```json
+{
+  "hash":          "8b54a3c2...",
+  "name":          "ubuntu-26.04-desktop-amd64.iso",
+  "ed2k_link":     "ed2k://|file|ubuntu...|3825..|8b54...|/",
+  "size":          3825205248,
+  "size_done":     1142000000,
+  "size_xfer":     1102450000,
+  "speed_bps":     4500000,
+  "status":        "downloading",
+  "priority":      "normal",
+  "priority_auto": true,
+  "category":      0,
+  "sources":  { "total": 217, "not_current": 23, "transferring": 8, "a4af": 4 },
+  "progress": { "percent": 29.85 }
+}
+```
+
+#### `download_removed`
+
+```json
+{ "hash": "8b54a3c2..." }
+```
+
+Only the hash; clients look up and drop the cache entry by hash.
+
+### `shared` channel
+
+#### `shared_added` / `shared_updated`
+
+Identical to the REST [`/api/v0/shared`](REFERENCE.md#get-apiv0shared) list-item shape. `_updated` fires on any field-level change including `xfer.session`, `xfer.total`, `requests.*`, and `accepts.*` — clients see live upload counters without polling.
+
+```json
+{
+  "hash":             "1a2b3c4d...",
+  "name":             "release-notes.txt",
+  "ed2k_link":        "ed2k://|file|release-notes.txt|3217|1a2b...|/",
+  "size":             3217,
+  "priority":         "normal",
+  "complete_sources": 12,
+  "xfer":     { "session": 5242880, "total": 314572800 },
+  "requests": { "session": 42,      "total": 1837 },
+  "accepts":  { "session": 18,      "total": 921 }
+}
+```
+
+#### `shared_removed`
+
+```json
+{ "hash": "1a2b3c4d..." }
+```
+
+### `servers` channel
+
+#### `server_added` / `server_updated`
+
+Identical to the REST [`/api/v0/servers`](REFERENCE.md#get-apiv0servers) list-item shape.
+
+```json
+{
+  "ecid":        1,
+  "name":        "eMule Server",
+  "description": "Public server",
+  "version":     "17.15",
+  "address":     "203.0.113.5:4242",
+  "port":        4242,
+  "users":       312000,
+  "max_users":   500000,
+  "files":       75000000,
+  "priority":    "normal",
+  "ping_ms":     42,
+  "failed":      0,
+  "static":      false
+}
+```
+
+#### `server_removed`
+
+```json
+{ "ecid": 1 }
+```
+
+Servers are ECID-keyed (not hash-keyed) so the removed payload carries the integer ECID.
+
+### `clients` channel
+
+#### `client_added` / `client_updated`
+
+Identical to the REST [`/api/v0/clients`](REFERENCE.md#get-apiv0clients) list-item shape. Speed fields move on every tick during active transfers, so the `clients` channel can be the loudest one on a busy node.
+
+```json
+{
+  "client_ecid":            4382,
+  "client_name":            "AnonymousPeer",
+  "user_hash":              "1f2e3a...",
+  "ip":                     "203.0.113.42",
+  "port":                   4662,
+  "software":               "eMule",
+  "software_version":       "0.50a",
+  "os_info":                "Linux",
+  "upload_state":           "uploading",
+  "download_state":         "idle",
+  "ident_state":            "verified",
+  "upload_file_hash":       "8b54a3c20fae9e4b9f7e0c2c8c01b6b1",
+  "download_file_hash":     "",
+  "download_file_name":     "",
+  "xfer": {
+    "up_session":   22000000,
+    "down_session": 0,
+    "up_total":     452000000,
+    "down_total":   189000000
+  },
+  "upload_speed_bps":       22000,
+  "download_speed_bps":     0,
+  "queue_waiting_position": 0,
+  "remote_queue_rank":      0,
+  "score":                  150,
+  "obfuscation_status":     "obfuscated",
+  "friend_slot":            false
+}
+```
+
+`upload_file_hash` (file we're uploading TO this peer) and `download_file_hash` (file we're downloading FROM this peer) are 32-char MD4 hex hashes — directly resolvable against [`/api/v0/downloads/{hash}`](REFERENCE.md#get-apiv0downloadshash) (in-progress) or the corresponding entry in [`/api/v0/shared`](REFERENCE.md#get-apiv0shared) by `.hash`. Either field can be empty when the peer is queued / idle in that direction.
+
+#### `client_removed`
+
+```json
+{ "client_ecid": 4382 }
+```
+
+### `status` channel
+
+#### `status_changed`
+
+Identical to the REST [`/api/v0/status`](REFERENCE.md#get-apiv0status) envelope. The payload is the post-change snapshot, not a diff. Fires when any field anywhere in the envelope changes — ed2k state, Kad state, Kad network counters, headline speeds, queue length, or `ec_connected`.
+
+```json
+{
+  "ec_connected": true,
+  "ed2k": {
+    "state":       "connected",
+    "low_id":      false,
+    "server_name": "eMule Server",
+    "server_ip":   "203.0.113.5",
+    "server_port": 4242
+  },
+  "kad": {
+    "state":      "connected",
+    "firewalled": false,
+    "network":    { "users": 5400000, "files": 1400000000, "nodes": 2400 }
+  },
+  "speeds": { "download_bps": 4500000, "upload_bps": 50000 },
+  "queue":  { "upload_queue_length": 12, "total_source_count": 1843 }
+}
+```
+
+Subscribe to this channel alone for a thin "header bar" client that just wants connection state and headline counters.
+
+### `logs` channel
+
+#### `log_appended`
+
+Emitted when the amuled log buffer appends new lines.
+
+```json
+{ "lines": ["2026-06-19 11:00:00: line one", "2026-06-19 11:00:01: line two"] }
+```
+
+Only the amuled log has a live channel; the serverinfo buffer has no SSE feed and is fetched by polling [`GET /logs/serverinfo`](REFERENCE.md#get-apiv0logsserverinfo). Multiple lines may be batched into a single event when the buffer landed several lines between refresher ticks. The [Bootstrap example](#bootstrap-snapshot--stream) doesn't pull `/logs/amule` — fetch it in step 2 if your UI shows historical log lines, otherwise treat `log_appended` as a live-only feed.
+
+### `search` channel
+
+Driven by the refresher state machine that owns the `POST /search` → completion lifecycle (see [REFERENCE.md](REFERENCE.md#search-results)). Events only fire while a search is active; the channel is silent at idle. The [Bootstrap example](#bootstrap-snapshot--stream) omits `/search/results` because searches are normally client-initiated post-boot; if your UI persists a "search-in-progress" state across reloads, fetch `/search/results` and `/search/progress` in step 2 too.
+
+#### `search_result_added`
+
+Emitted per new result that appears in the results map between refresher ticks.
+
+```json
+{
+  "hash": "0123456789abcdef0123456789abcdef",
+  "name": "ubuntu-24.04-desktop-amd64.iso",
+  "size": 5765873664,
+  "sources": { "total": 12, "complete": 7 },
+  "already_have": false,
+  "rating": 0
+}
+```
+
+Key results by `hash`. The payload is byte-for-byte identical to a `/search/results` array entry (`sources` is the nested `{total, complete}` object, same as the REST endpoint). amuled wipes its searchlist on every new `POST /search`, so subscribers must treat each search as a fresh result space — clear prior results when you start a new query.
+
+#### `search_progress`
+
+Emitted whenever the current search's completion advances and once more on completion. Two triggers, both off the daemon's unambiguous `EC_TAG_SEARCH_LIFECYCLE_*` tags (see [REFERENCE.md](REFERENCE.md#search-results)): the `percent` changing between refresher ticks while the search runs, and the lifecycle flipping to finished (the `state` `running` → `finished` edge). The completion frame is just the terminal `search_progress` with `"state": "finished"` — there is **no** separate `search_finished` event.
+
+```json
+{ "state": "running", "percent": 47, "results": 88, "kind": "kad" }
+```
+
+```json
+{ "state": "finished", "percent": 100, "results": 153, "kind": "local" }
+```
+
+- `state` — `"running"` while the search is in flight, `"finished"` on the terminal frame.
+- `percent` — `0..100`, daemon-computed for every search kind. For **global** it is the real server-queue progress. For **Kad**, which has no measurable progress, it is a cosmetic time-ramp derived from the fixed 45 s keyword-search lifetime (capped at 99 until the daemon authoritatively reports completion, then 100); see [REFERENCE.md](REFERENCE.md#search-results). Treat the Kad value as a liveliness indicator, not an accurate completion estimate.
+- `kind` — the originally-requested search type (`"local"` | `"global"` | `"kad"`).
+- `results` — the current results-map size; subscribers can reconcile against any `search_result_added` they may have missed via `GET /search/results`.
+
+A Kad search hitting its result cap (`SEARCHKEYWORD_TOTAL`, 300) before the 45 s deadline finishes early — the lifecycle flips to `finished` and `percent` jumps straight to 100 ahead of the ramp.
+
+### Filter-bypass: `resync`
+
+The synthetic `resync` event has no underscore prefix — it doesn't belong to any of the channel buckets above and is always delivered regardless of `?channels=`. Documented under [Reconnect and Last-Event-ID](#reconnect-and-last-event-id).
+
+## Single-publisher invariant
+
+Only the wxApp refresher tick publishes diffs onto the bus. A future inline-refresh-then-publish path from an HTTP-thread mutation would silently race the refresher's diff walk; the daemon's debug build asserts this and the release build hard-aborts. End-user impact: events are strictly ordered by `id`, monotonically, with no interleavings between distinct publishers.
+
+## Shutdown behaviour
+
+When the daemon receives `SIGINT` / `SIGTERM`, the event bus is latched into a shutdown state, every in-flight `Drain()` wakes immediately and returns no events, and every live SSE socket is closed from the I/O thread. A subscriber loop sees the underlying stream go dead, exits the read loop, and reconnects on its normal backoff. EventSource handles this with no application code on the client side.
diff --git a/docs/api/REFERENCE.md b/docs/api/REFERENCE.md
new file mode 100644
index 0000000000..a9ba7c1833
--- /dev/null
+++ b/docs/api/REFERENCE.md
@@ -0,0 +1,1140 @@
+# amuleapi v0 — REST reference
+
+This document is the contract for every REST endpoint exposed by the `amuleapi` daemon under the `/api/v0/` prefix. For the SSE stream see [EVENTS.md](EVENTS.md). For first-run setup see [../QUICKSTART-AMULEAPI.md](../QUICKSTART-AMULEAPI.md).
+
+The API is versioned in the path. Breaking changes ship under `/api/v1/`; `/api/v0/` is frozen against any backwards-incompatible change for the lifetime of the v0 surface.
+
+## Index
+
+**Cross-cutting concerns**
+- [Base URL and transport](#base-url-and-transport)
+- [Authentication](#authentication) — [Login response shape](#login-response-shape), [Role model](#role-model), [Rate limiting](#rate-limiting), [JWT structure](#jwt-structure)
+- [Response model](#response-model) — [Success envelope](#success-envelope), [Error envelope](#error-envelope), [ETag and conditional GET](#etag-and-conditional-get), [CORS](#cors), [Path validation](#path-validation), [Request size limits](#request-size-limits)
+- [Error code catalog](#error-code-catalog)
+- [Backward compatibility](#backward-compatibility)
+
+**System**
+- [`GET /api/v0/version`](#get-apiv0version) — public version probe
+- [`GET /api/v0/status`](#get-apiv0status) — connection state, network state, headline counters
+
+**Authentication**
+- [`POST /api/v0/auth/login`](#post-apiv0authlogin) — mint a JWT, optionally return it in the body
+- [`POST /api/v0/auth/logout`](#post-apiv0authlogout) — revoke the bearer's `jti`
+- [`GET /api/v0/auth/session`](#get-apiv0authsession) — verified bearer's role and expiry
+
+**Downloads**
+- [`GET /api/v0/downloads`](#get-apiv0downloads) — list active queue
+- [`GET /api/v0/downloads/{hash}`](#get-apiv0downloadshash) — detail view; `{hash}` is the 32-char MD4 hex hash
+- [`POST /api/v0/downloads`](#post-apiv0downloads) — add ed2k link(s)
+- [`PATCH /api/v0/downloads/{hash}`](#patch-apiv0downloadshash) — pause / resume / priority / category
+- [`DELETE /api/v0/downloads/{hash}`](#delete-apiv0downloadshash) — cancel + remove
+- [`POST /api/v0/downloads/clear_completed`](#post-apiv0downloadsclear_completed) — bulk-clear completed staging buffer
+
+**Clients (peers)**
+- [`GET /api/v0/clients`](#get-apiv0clients) — list peers, optional filter
+
+**Shared files**
+- [`GET /api/v0/shared`](#get-apiv0shared) — list shared files
+- [`POST /api/v0/shared/reload`](#post-apiv0sharedreload) — re-walk shared directories
+- [`PATCH /api/v0/shared/{hash}`](#patch-apiv0sharedhash) — change upload priority
+
+**Servers**
+- [`GET /api/v0/servers`](#get-apiv0servers) — list known ed2k servers
+- [`POST /api/v0/servers`](#post-apiv0servers) — add server
+- [`POST /api/v0/servers/{ecid}/connect`](#post-apiv0serversecidconnect--post-apiv0serversipportconnect) — connect to specific server (ECID or `ip:port`)
+- [`DELETE /api/v0/servers/{ecid}`](#delete-apiv0serversecid--delete-apiv0serversipport) — remove server (ECID or `ip:port`)
+- [`POST /api/v0/servers/update`](#post-apiv0serversupdate) — refresh from `server.met` URL
+
+**Categories**
+- [`GET /api/v0/categories`](#get-apiv0categories) — list categories
+- [`POST /api/v0/categories`](#post-apiv0categories) — create
+- [`PATCH /api/v0/categories/{index}`](#patch-apiv0categoriesindex) — modify
+- [`DELETE /api/v0/categories/{index}`](#delete-apiv0categoriesindex) — remove
+
+**Preferences**
+- [`GET /api/v0/preferences`](#get-apiv0preferences) — read connection + general prefs
+- [`PATCH /api/v0/preferences`](#patch-apiv0preferences) — update subset of prefs
+
+**Network control**
+- [`POST /api/v0/networks/connect`](#post-apiv0networksconnect) — connect ed2k / kad / both
+- [`POST /api/v0/networks/disconnect`](#post-apiv0networksdisconnect) — disconnect ed2k / kad / both
+- [`POST /api/v0/kad/bootstrap`](#post-apiv0kadbootstrap) — single-contact Kad bootstrap
+- [`GET /api/v0/kad`](#get-apiv0kad) — Kad-only status subtree
+
+**Logs**
+- [`GET /api/v0/logs/amule`](#get-apiv0logsamule) — amule log buffer
+- [`DELETE /api/v0/logs/amule`](#delete-apiv0logsamule) — clear amule buffer
+- [`GET /api/v0/logs/serverinfo`](#get-apiv0logsserverinfo--delete-apiv0logsserverinfo) — server-info log buffer
+- [`DELETE /api/v0/logs/serverinfo`](#get-apiv0logsserverinfo--delete-apiv0logsserverinfo) — clear server-info buffer
+
+**Statistics**
+- [`GET /api/v0/stats/tree`](#get-apiv0statstree) — full statistics tree
+- [`GET /api/v0/stats/graphs/{graph}`](#get-apiv0statsgraphsgraph) — time-series points (`download`, `upload`, `connections`, `kad`)
+
+**Search**
+- [`POST /api/v0/search`](#post-apiv0search) — start a search (global / local / kad)
+- [`GET /api/v0/search/results`](#get-apiv0searchresults) — current results + progress envelope
+- [`POST /api/v0/search/stop`](#post-apiv0searchstop) — cancel in-flight search
+- [`POST /api/v0/search/results/{hash}/download`](#post-apiv0searchresultshashdownload) — promote a result into the download queue
+
+## Base URL and transport
+
+`amuleapi` serves HTTP on the address declared in `amuleapi.conf[Server]/Port` (default `4713`). The server is HTTP-only by design — terminate TLS in a reverse proxy (nginx, Caddy, etc.) for any non-loopback deployment. The cookie is deliberately NOT marked `Secure` so the same Set-Cookie works whether the operator runs amuleapi behind TLS or directly. See QUICKSTART for the full bind-vs-listen story.
+
+JSON in, JSON out. Every request body that carries a payload is `Content-Type: application/json`. Every response that carries a payload is `application/json` unless explicitly noted (the SSE endpoint emits `text/event-stream`).
+
+## Authentication
+
+Two carriers, one token. amuleapi mints HS256 JWTs at `/auth/login` and accepts them either as:
+
+- An `Authorization: Bearer <jwt>` header (SDK / curl / server-to-server clients).
+- An HttpOnly session cookie named `amuleapi_token` (browser clients).
+
+If both arrive on the same request, the bearer header wins. The cookie attributes are `HttpOnly; SameSite=Strict; Path=/api/v0`. Cookie lifetime tracks the JWT's `exp` claim (`Max-Age = expires_at - now`).
+
+### Login response shape
+
+The JSON body of `POST /auth/login` deliberately omits the token by default — XSS that can `fetch('/auth/login', ...)` and read the body would defeat the HttpOnly protection. Browser clients work entirely off the Set-Cookie attached to the response. SDK clients that need the token in the body opt in via either:
+
+- `?type=bearer` query string, or
+- `Accept: application/jwt` request header.
+
+| Mode | Body keys | Set-Cookie |
+|------|-----------|------------|
+| Default (cookie) | `role`, `expires_at`, `expires_at_unix` | yes |
+| Bearer opt-in | `token`, `role`, `expires_at`, `expires_at_unix`, `jti` | yes (cookie also goes out so a hybrid client can use either) |
+
+### Role model
+
+Two roles, both gated by separate passwords configured via the `--set-admin-pass` / `--set-guest-pass` CLI commands:
+
+- `admin` — full surface, including every mutation (`POST`, `PATCH`, `DELETE`).
+- `guest` — read-only surface. Any `admin`-only endpoint returns `403 forbidden`.
+
+A role is implicitly assigned at login based on which password matched; the verified role is encoded in the JWT and surfaced on `/auth/session`.
+
+### Rate limiting
+
+Two per-IP failure counters, both with sliding-window semantics:
+
+- **Login limiter** — drives `/auth/login`. Defaults are `[Auth]/LoginFailureWindowSeconds=60`, `LoginFailureThreshold=5`, `LoginLockoutSeconds=300`. Configurable per-deployment.
+- **Generic 401 limiter** — drives every other auth-protected endpoint. Fixed at 30 failures in 60 s → 5-minute lockout. Catches credential-stuffing across the non-login surface.
+
+When the bucket fills, the next request from that IP returns `429 rate_limited` with a `Retry-After: <seconds>` header. The bucket clears on success or when the lockout expires.
+
+### JWT structure
+
+Header: `{"alg":"HS256","typ":"JWT"}`. Payload: `{"role":"admin"|"guest","iat":<unix>,"exp":<unix>,"jti":"<base64url>"}`. The signing secret is auto-generated as 32 random bytes into `${config_dir}/amuleapi-jwt-secret` on first launch (mode 0600). Delete that file and restart to invalidate every issued token. The `jti` claim drives the server-side revocation list (`/auth/logout`).
+
+## Response model
+
+### Success envelope
+
+Each endpoint documents its own response shape under the endpoint section. List endpoints wrap their array under the resource plural name (`{"downloads": [...]}`, `{"shared": [...]}`) so clients can extend the envelope with sibling metadata without breaking JSON-parser pipelines.
+
+### Error envelope
+
+Every non-2xx response carries the same shape:
+
+```json
+{
+  "error": {
+    "code": "machine_readable_token",
+    "message": "human-readable explanation"
+  }
+}
+```
+
+`code` is stable across releases; alert on `code`, not on `message`. The catalog at the bottom of this file lists every code emitted by the dispatcher.
+
+### ETag and conditional GET
+
+Every `GET` or `HEAD` that returns `200` carries an `ETag: "<md5-hex>"` header. Clients that re-fetch should send `If-None-Match: "<etag>"` and accept `304 Not Modified` (no body, ETag preserved). The ETag is keyed on `(request target, last refresher snapshot timestamp)` and memoized — repeated GETs against the same path between refresher ticks skip the body hash entirely. `HEAD` returns the same headers (including ETag) with an empty body.
+
+Mutations (`POST`/`PATCH`/`DELETE`) and error responses are never ETag-stamped; the body always ships.
+
+### CORS
+
+If `amuleapi.conf[Server]/AllowCORS=1`:
+
+- Every response carries `Vary: Origin`.
+- The origin is echoed in `Access-Control-Allow-Origin` if either the allowlist is empty (any-origin echo) or the request's `Origin` header matches a configured entry.
+- Allowed responses also carry `Access-Control-Allow-Credentials: true` and `Access-Control-Expose-Headers: ETag` so cookie-auth clients can read the validator from JS.
+- Preflight (`OPTIONS` with `Access-Control-Request-Method`) returns `204` with `Access-Control-Allow-Methods: GET, HEAD, POST, PATCH, DELETE, OPTIONS`, `Access-Control-Allow-Headers: Authorization, Content-Type, If-None-Match, Last-Event-ID`, and `Access-Control-Max-Age: 86400`.
+
+### Path validation
+
+The dispatcher rejects paths containing NUL, encoded NUL (`%00`), encoded `..` (any case of `%2e%2e`), or a literal `..` segment with `400 bad_request` before routing. Defence-in-depth against a future endpoint that admits path captures.
+
+### Request size limits
+
+- HTTP header section: hard cap 16 KiB.
+- Request body: hard cap 1 MiB.
+- JSON nesting: `>32` opening `{` or `[` tokens → `400 bad_request`. Applies to every body parser and to the JWT header/payload sections of bearer tokens.
+
+Above any of these, the connection is rejected before the handler runs.
+
+## Endpoint catalog
+
+The catalog below is grouped by resource. Each entry documents:
+
+- **Method + path**
+- **Auth** — `NONE`, `GUEST` (any authenticated role), or `ADMIN`
+- **Query parameters** if any
+- **Request body schema** for endpoints that consume one
+- **Response status + body**
+- **Error codes the endpoint can emit** beyond the universal `unauthorized` / `forbidden` / `rate_limited` (those are documented in §Response model above and are not repeated per endpoint)
+
+Curl examples use `$HOST` for `127.0.0.1:4713` and `$TOKEN` for a previously-issued bearer.
+
+---
+
+### System
+
+#### `GET /api/v0/version`
+
+**Auth:** `NONE` — always accessible, useful for health probes and version negotiation by SDK clients.
+
+```sh
+curl -s http://$HOST/api/v0/version
+```
+
+**Response:** `200 OK`
+
+```json
+{
+  "name": "amuleapi",
+  "api_version": "v0",
+  "amule_version": "2.4.0-29-g..."
+}
+```
+
+#### `GET /api/v0/status`
+
+**Auth:** `GUEST`
+
+Returns the current connection state, network state, and headline throughput counters.
+
+```sh
+curl -s -H "Authorization: Bearer $TOKEN" http://$HOST/api/v0/status
+```
+
+**Response:** `200 OK`
+
+```json
+{
+  "ec_connected": true,
+  "ed2k": {
+    "state": "connected",
+    "low_id": false,
+    "server_name": "eMule Server",
+    "server_ip": "203.0.113.5",
+    "server_port": 4242
+  },
+  "kad": {
+    "state": "connected",
+    "firewalled": false,
+    "network": { "users": 5400000, "files": 1400000000, "nodes": 2400 }
+  },
+  "speeds": { "download_bps": 4500000, "upload_bps": 50000 },
+  "queue": { "upload_queue_length": 12, "total_source_count": 1843 }
+}
+```
+
+`ec_connected` is `false` while amuleapi can't reach the underlying amuled. Most other endpoints return `503 ec_unavailable` in that state.
+
+**Errors:** `503 ec_unavailable` if amuleapi hasn't received its first EC snapshot yet.
+
+---
+
+### Authentication
+
+#### `POST /api/v0/auth/login`
+
+**Auth:** `NONE`
+
+Mints a JWT for the role that matched the supplied password.
+
+**Query parameters:** `?type=bearer` (optional) — opt into the bearer body response shape. Equivalent to sending `Accept: application/jwt`.
+
+**Body:**
+
+```json
+{ "password": "string" }
+```
+
+**Default (cookie) request:**
+
+```sh
+curl -i -X POST http://$HOST/api/v0/auth/login \
+  -H 'Content-Type: application/json' \
+  -d '{"password":"adminpass"}'
+```
+
+```
+HTTP/1.1 200 OK
+Set-Cookie: amuleapi_token=eyJhbGciOi...; HttpOnly; SameSite=Strict; Path=/api/v0; Max-Age=86400
+Content-Type: application/json
+
+{"role":"admin","expires_at":"2026-06-20T11:00:00Z","expires_at_unix":1781434800}
+```
+
+**Bearer opt-in request:**
+
+```sh
+curl -s -X POST "http://$HOST/api/v0/auth/login?type=bearer" \
+  -H 'Content-Type: application/json' \
+  -d '{"password":"adminpass"}'
+```
+
+```json
+{
+  "token": "eyJhbGciOi...",
+  "role": "admin",
+  "expires_at": "2026-06-20T11:00:00Z",
+  "expires_at_unix": 1781434800,
+  "jti": "b3iY9oA1tUW2pK..."
+}
+```
+
+**Errors:**
+
+- `400 bad_request` — body missing/non-object/missing `password`/non-string `password`.
+- `401 invalid_credentials` — password didn't match any configured role.
+- `429 rate_limited` — login limiter armed; `Retry-After` set.
+- `503 login_disabled` — no admin and no guest password configured.
+
+#### `POST /api/v0/auth/logout`
+
+**Auth:** `GUEST`
+
+Adds the bearer's `jti` to the server-side revocation list (TTL = JWT's `exp`) and emits a clear-cookie. Idempotent: a token that is already revoked still gets `200 OK` so a double-tap on a logout button doesn't surface a confusing "session expired" toast.
+
+```sh
+curl -i -X POST -H "Authorization: Bearer $TOKEN" http://$HOST/api/v0/auth/logout
+```
+
+```json
+{ "ok": true }
+```
+
+**Response headers:** `Set-Cookie: amuleapi_token=; HttpOnly; SameSite=Strict; Path=/api/v0; Max-Age=0`.
+
+#### `GET /api/v0/auth/session`
+
+**Auth:** `GUEST`
+
+Returns the verified bearer's role and expiry. Useful for SPA bootstrap.
+
+```sh
+curl -s -H "Authorization: Bearer $TOKEN" http://$HOST/api/v0/auth/session
+```
+
+```json
+{
+  "role": "admin",
+  "exp": "2026-06-20T11:00:00Z",
+  "exp_unix": 1781434800,
+  "jti": "b3iY9oA1tUW2pK..."
+}
+```
+
+---
+
+### Downloads
+
+#### `GET /api/v0/downloads`
+
+**Auth:** `GUEST`
+
+Lists the current transfer queue. Completed entries (status `completed`) are excluded by default — they live in amuled's separate "awaiting clear" list and surfacing them inline confuses queue dashboards.
+
+**Query parameters:**
+
+- `include_completed=1|true|yes` — opt completed entries back in.
+
+```sh
+curl -s -H "Authorization: Bearer $TOKEN" "http://$HOST/api/v0/downloads"
+```
+
+```json
+{
+  "downloads": [
+    {
+      "hash":          "8b54a3c2...",
+      "name":          "ubuntu-26.04-desktop-amd64.iso",
+      "ed2k_link":     "ed2k://|file|ubuntu...|3825..|8b54...|/",
+      "size":          3825205248,
+      "size_done":     1142000000,
+      "size_xfer":     1102450000,
+      "speed_bps":     4500000,
+      "status":        "downloading",
+      "priority":      "normal",
+      "priority_auto": true,
+      "category":      0,
+      "sources":  { "total": 217, "not_current": 23, "transferring": 8, "a4af": 4 },
+      "progress": { "percent": 29.85 }
+    }
+  ]
+}
+```
+
+The list shape omits `progress.parts` to keep large libraries compact. Use the detail endpoint for per-part state.
+
+The SSE `download_added` / `download_updated` event payload matches this object byte-for-byte.
+
+**Errors:** `503 ec_unavailable`.
+
+#### `GET /api/v0/downloads/{hash}`
+
+**Auth:** `GUEST`
+
+Detail view for a single partfile. `{hash}` is the 32-char MD4 hex hash (case-insensitive).
+
+```sh
+curl -s -H "Authorization: Bearer $TOKEN" \
+  "http://$HOST/api/v0/downloads/8b54a3c20fae9e4b9f7e0c2c8c01b6b1"
+```
+
+Same envelope as the list item, plus a `progress.parts` array — one entry per ~9.28 MiB chunk with `state` (transferring / complete / empty / corrupt / etc.) and `sources` (count of peers offering that chunk).
+
+**Errors:** `404 not_found` (no partfile with that hash), `503 ec_unavailable`.
+
+#### `POST /api/v0/downloads`
+
+**Auth:** `ADMIN`
+
+Adds one or more ed2k links to the transfer queue.
+
+**Body** (one of two forms, mutually exclusive):
+
+```json
+{ "ed2k_link": "ed2k://|file|...|/", "category": 0 }
+```
+
+```json
+{ "links": ["ed2k://|file|a|...|/", "ed2k://|file|b|...|/"], "category": 0 }
+```
+
+`category` is optional (defaults to 0). Mixing `ed2k_link` and `links` in the same body is rejected `400`.
+
+```sh
+curl -s -X POST -H "Authorization: Bearer $TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d '{"links":["ed2k://|file|a|...|/", "ed2k://|file|b|...|/"]}' \
+  "http://$HOST/api/v0/downloads"
+```
+
+**Response:** `202 Accepted` (all links accepted), `207 Multi-Status` (partial), or `503 ec_unavailable` (every link rejected by EC).
+
+```json
+{
+  "ok": true,
+  "accepted": 1,
+  "failed": 1,
+  "disconnected": 0,
+  "accepted_links": ["ed2k://|file|a|...|/"],
+  "failed_links":   ["ed2k://|file|b|...|/"],
+  "first_error":    "malformed ed2k link"
+}
+```
+
+**Errors:** `400 bad_request` (malformed body, both forms used, non-string link), `503 ec_unavailable`.
+
+#### `PATCH /api/v0/downloads/{hash}`
+
+**Auth:** `ADMIN`
+
+Mutates one or more fields of a single partfile. `{hash}` is the 32-char MD4 hex hash (case-insensitive).
+
+**Body:** at least one of:
+
+- `status` — `"paused"` or `"resumed"`
+- `priority` — `"very_low"` / `"low"` / `"normal"` / `"high"` / `"release"` / `"auto"`
+- `category` — uint8
+
+```sh
+curl -s -X PATCH -H "Authorization: Bearer $TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d '{"status":"paused"}' \
+  "http://$HOST/api/v0/downloads/8b54a3c2..."
+```
+
+**Response:** `200 OK` — the updated download object (full detail envelope including `progress.parts`).
+
+**Errors:** `400 bad_request` (no recognised field, invalid enum), `400 amuled_rejected`, `404 not_found`, `503 ec_unavailable`.
+
+#### `DELETE /api/v0/downloads/{hash}`
+
+**Auth:** `ADMIN`
+
+Cancels an **active** partfile and deletes its on-disk data. `{hash}` is the 32-char MD4 hex hash (case-insensitive). amuled runs `EC_OP_PARTFILE_DELETE` → `CPartFile::Delete()`, which removes the `.part`, `.part.met`, and `.met.bak` files and adds the hash to its `canceledfiles` list (so re-adding the same ed2k link is silently refused until the operator clears that list out-of-band). Completed entries are out of scope; use [`POST /downloads/clear_completed`](#post-apiv0downloadsclear_completed) instead.
+
+```sh
+curl -s -X DELETE -H "Authorization: Bearer $TOKEN" \
+  "http://$HOST/api/v0/downloads/8b54a3c2..."
+```
+
+```json
+{ "ok": true, "hash": "8b54a3c2..." }
+```
+
+**Errors:** `400 amuled_rejected`, `404 not_found`, `409 completed_use_clear_completed`, `503 ec_unavailable`.
+
+#### `POST /api/v0/downloads/clear_completed`
+
+**Auth:** `ADMIN`
+
+Acks one or more entries in amuled's post-completion notification staging buffer. The on-disk file in the Incoming directory stays in place; this endpoint only clears amuled's "completed transfers awaiting acknowledgement" list. Active partfiles are out of scope; use [`DELETE /api/v0/downloads/{hash}`](#delete-apiv0downloadshash) instead.
+
+Two request shapes share this endpoint:
+
+```sh
+# Bulk: no body. Clears every completed entry in one EC roundtrip.
+curl -s -X POST -H "Authorization: Bearer $TOKEN" \
+  "http://$HOST/api/v0/downloads/clear_completed"
+
+# Per-entry: clear a single completed entry by hash.
+curl -s -X POST -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"hash": "8b54a3c2..."}' \
+  "http://$HOST/api/v0/downloads/clear_completed"
+```
+
+The response envelope is identical for both shapes:
+
+```json
+{ "ok": true, "cleared": 3, "cleared_hashes": ["...", "...", "..."] }
+```
+
+Bulk form returns `200 OK` with `cleared: 0` and no `cleared_hashes` field when nothing matches (no-op success, distinguishable from an amuled rejection). Per-entry form returns `404 not_found` if the hash doesn't exist and `409 not_completed` if it exists but isn't on the completed staging list (active partfile — caller probably wants `DELETE /downloads/{hash}` instead).
+
+**Errors:** `400 amuled_rejected`, `400 bad_request` (malformed body or non-string `hash`), `404 not_found`, `409 not_completed`, `503 ec_unavailable`.
+
+---
+
+### Clients (peers)
+
+#### `GET /api/v0/clients`
+
+**Auth:** `GUEST`
+
+Lists the peers amuled is currently exchanging with.
+
+**Query parameters:**
+
+- `filter=uploads` — peers we are currently uploading to (`upload_state == "uploading"`).
+- `filter=downloads` — peers we are currently downloading from (`download_state == "downloading"`).
+- `filter=active` — peers that are either uploading or downloading right now.
+- Default (no filter) — every known peer, including queued.
+
+```sh
+curl -s -H "Authorization: Bearer $TOKEN" \
+  "http://$HOST/api/v0/clients?filter=active"
+```
+
+```json
+{
+  "clients": [
+    {
+      "client_ecid": 4382,
+      "client_name": "AnonymousPeer",
+      "user_hash": "1f2e3a...",
+      "ip": "203.0.113.42",
+      "port": 4662,
+      "software": "eMule",
+      "software_version": "0.50a",
+      "os_info": "Linux",
+      "upload_state": "uploading",
+      "download_state": "idle",
+      "ident_state": "verified",
+      "download_file_name": "",
+      "upload_file_hash": "8b54a3c20fae9e4b9f7e0c2c8c01b6b1",
+      "download_file_hash": "",
+      "xfer": { "up_session": 22000000, "down_session": 0, "up_total": 452000000, "down_total": 189000000 },
+      "upload_speed_bps": 22000,
+      "download_speed_bps": 0,
+      "queue_waiting_position": 0,
+      "remote_queue_rank": 0,
+      "score": 150,
+      "obfuscation_status": "obfuscated",
+      "friend_slot": false
+    }
+  ]
+}
+```
+
+`client_ecid` identifies the remote *peer*, not a file — it's the URL key reserved for any future `/clients/{client_ecid}` mutation and the identity carried in `client_removed` SSE payloads. `user_hash` is the peer's stable identity *when published* (peers without SecIdent or in their first session don't have one), so `client_ecid` is the always-populated handle.
+
+`upload_file_hash` / `download_file_hash` are the 32-char MD4 hex hashes of the partfile or shared file the peer is currently transferring with — directly resolvable against [`/api/v0/downloads/{hash}`](#get-apiv0downloadshash) (in-progress) or the corresponding entry in [`/api/v0/shared`](#get-apiv0shared) by `.hash`. Either field can be empty when the peer is queued / idle in that direction. `download_file_name` is the filename the peer advertised in `OP_REQFILENAMEANSWER` and is populated only while we're actively downloading from them.
+
+**Errors:** `400 bad_request` (unknown filter token), `503 ec_unavailable`.
+
+---
+
+### Shared files
+
+#### `GET /api/v0/shared`
+
+**Auth:** `GUEST`
+
+Lists every file the local node is sharing. The `complete_sources` counter is amuled's estimate of how many peers in the swarm hold the file complete.
+
+```sh
+curl -s -H "Authorization: Bearer $TOKEN" "http://$HOST/api/v0/shared"
+```
+
+```json
+{
+  "shared": [
+    {
+      "hash":             "1a2b3c4d...",
+      "name":             "release-notes.txt",
+      "ed2k_link":        "ed2k://|file|release-notes.txt|3217|1a2b...|/",
+      "size":             3217,
+      "priority":         "normal",
+      "complete_sources": 12,
+      "xfer":     { "session": 5242880,  "total": 314572800 },
+      "requests": { "session": 42,       "total": 1837 },
+      "accepts":  { "session": 18,       "total": 921 }
+    }
+  ]
+}
+```
+
+`xfer.session` / `xfer.total` are bytes uploaded during the current amuled process vs over the file's lifetime. `requests` counts how many peers have asked for the file; `accepts` counts how many of those requests were granted an upload slot. The `session` counters reset on amuled restart; `total` is persisted in `known.met`.
+
+The SSE `shared_added` / `shared_updated` event payload matches this object byte-for-byte, so a subscriber that received `shared_updated` does not need to re-GET to see the moved counters.
+
+**Errors:** `503 ec_unavailable`.
+
+#### `POST /api/v0/shared/reload`
+
+**Auth:** `ADMIN`
+
+Equivalent to the desktop client's "Reload" button — amuled re-walks its shared directories and updates the file list.
+
+```sh
+curl -s -X POST -H "Authorization: Bearer $TOKEN" \
+  "http://$HOST/api/v0/shared/reload"
+```
+
+```json
+{ "ok": true }
+```
+
+Returns `202 Accepted`.
+
+**Errors:** `503 ec_unavailable`.
+
+#### `PATCH /api/v0/shared/{hash}`
+
+**Auth:** `ADMIN`
+
+Changes the upload priority of a single shared file. `{hash}` is the 32-char MD4 hex hash (case-insensitive).
+
+**Body:**
+
+```json
+{ "priority": "very_low" | "low" | "normal" | "high" | "release" }
+```
+
+**Errors:** `400 bad_request`, `400 amuled_rejected`, `503 ec_unavailable`.
+
+---
+
+### Servers (ed2k server list)
+
+#### `GET /api/v0/servers`
+
+**Auth:** `GUEST`
+
+```json
+{
+  "servers": [
+    {
+      "ecid": 1,
+      "name": "eMule Server",
+      "description": "Public server",
+      "version": "17.15",
+      "address": "203.0.113.5:4242",
+      "port": 4242,
+      "users": 312000,
+      "max_users": 500000,
+      "files": 75000000,
+      "priority": "normal",
+      "ping_ms": 42,
+      "failed": 0,
+      "static": false
+    }
+  ]
+}
+```
+
+**Errors:** `503 ec_unavailable`.
+
+#### `POST /api/v0/servers`
+
+**Auth:** `ADMIN`
+
+Add a server to amuled's known-server list.
+
+**Body:**
+
+```json
+{ "address": "203.0.113.5:4242", "name": "eMule Server" }
+```
+
+`name` optional; `address` required and must parse as `host:port`.
+
+**Response:** `201 Created` → `{ "ok": true, "address": "..." }`.
+
+**Errors:** `400 bad_request`, `400 amuled_rejected`, `503 ec_unavailable`.
+
+#### `POST /api/v0/servers/{ecid}/connect` / `POST /api/v0/servers/{ip}:{port}/connect`
+
+**Auth:** `ADMIN`
+
+Tells amuled to disconnect from its current server and dial the specified one. Two route shapes are equivalent — the address form looks up the ECID by exact `(ip, port)` match against the server cache and delegates to the ECID handler. Hostname-form addresses do NOT resolve here — pass the literal IP.
+
+```sh
+curl -s -X POST -H "Authorization: Bearer $TOKEN" \
+  "http://$HOST/api/v0/servers/203.0.113.5:4242/connect"
+```
+
+**Response:** `202 Accepted` → `{ "ok": true, "ecid": 1 }`.
+
+**Errors:** `400 bad_request` (unparseable address/ECID), `404 not_found`, `503 ec_unavailable`.
+
+#### `DELETE /api/v0/servers/{ecid}` / `DELETE /api/v0/servers/{ip}:{port}`
+
+**Auth:** `ADMIN`
+
+Removes the server from amuled's list.
+
+**Response:** `200 OK` → `{ "ok": true, "ecid": 1 }`.
+
+**Errors:** `400 amuled_rejected`, `404 not_found`, `503 ec_unavailable`.
+
+#### `POST /api/v0/servers/update`
+
+**Auth:** `ADMIN`
+
+Tells amuled to fetch the `server.met` from the supplied URL and refresh its list. Same operation the desktop GUI's "Update server list from URL" button drives.
+
+**Body:**
+
+```json
+{ "servers_url": "http://example.com/server.met" }
+```
+
+The URL must start with `http://` or `https://`; anything else is rejected `400 bad_request`.
+
+**Response:** `202 Accepted` → `{ "ok": true, "servers_url": "..." }`.
+
+**Errors:** `400 bad_request`, `400 amuled_rejected`, `503 ec_unavailable`.
+
+---
+
+### Categories
+
+amuled's category system lets users tag downloads with one of N user-defined buckets (separate save directory, separate priority, separate color). Category 0 is the default "Uncategorized" and cannot be deleted.
+
+#### `GET /api/v0/categories`
+
+**Auth:** `GUEST`
+
+```json
+{
+  "categories": [
+    {
+      "index": 0,
+      "name": "All",
+      "path": "/home/user/aMule/Incoming",
+      "comment": "",
+      "color": 0,
+      "priority": "normal"
+    }
+  ]
+}
+```
+
+**Errors:** `503 ec_unavailable`.
+
+#### `POST /api/v0/categories`
+
+**Auth:** `ADMIN`
+
+**Body:**
+
+```json
+{
+  "name": "Linux ISOs",
+  "path": "/home/user/aMule/Incoming/Linux",
+  "comment": "Distros only",
+  "color": 16711680,
+  "priority": "high"
+}
+```
+
+`name` required; others optional. `color` is a 24-bit RGB integer; `priority` is the same enum the shared-file PATCH accepts.
+
+**Response:** `201 Created` → the new category object.
+
+**Errors:** `400 bad_request`, `400 amuled_rejected`, `503 ec_unavailable`.
+
+#### `PATCH /api/v0/categories/{index}`
+
+**Auth:** `ADMIN`
+
+Any subset of the POST body fields. `index 0` (the default category) can be patched but not deleted.
+
+#### `DELETE /api/v0/categories/{index}`
+
+**Auth:** `ADMIN`
+
+```json
+{ "ok": true, "index": 1 }
+```
+
+Deleting `index 0` is rejected by amuled (`400 amuled_rejected`).
+
+---
+
+### Preferences
+
+#### `GET /api/v0/preferences`
+
+**Auth:** `GUEST`
+
+```json
+{
+  "general": {
+    "nickname": "MyNode",
+    "user_hash": "abcd...",
+    "host_name": "host.example.com",
+    "check_new_version": true
+  },
+  "connection": {
+    "max_upload_kbps":   50,
+    "max_download_kbps": 0,
+    "slot_allocation":   3,
+    "tcp_port":          4662,
+    "udp_port":          4672,
+    "udp_disabled":      false,
+    "max_sources_per_file": 250,
+    "max_connections":      400,
+    "autoconnect": true,
+    "reconnect":   true,
+    "network_ed2k": true,
+    "network_kad":  true
+  }
+}
+```
+
+**Errors:** `503 ec_unavailable`.
+
+#### `PATCH /api/v0/preferences`
+
+**Auth:** `ADMIN`
+
+Body shape mirrors the GET; every field is optional. Fields not present are left unchanged. Subset example:
+
+```json
+{ "connection": { "max_upload_kbps": 100 } }
+```
+
+**Response:** `200 OK` — full preferences object (post-mutation).
+
+**Errors:** `400 bad_request`, `400 amuled_rejected`, `503 ec_unavailable`.
+
+---
+
+### Network control
+
+These endpoints drive amuled's connect/disconnect to the ed2k network, the Kad network, or both.
+
+#### `POST /api/v0/networks/connect`
+
+**Auth:** `ADMIN`
+
+**Body:** `{ "network": "ed2k" | "kad" | "both" }` (optional; defaults to `"both"`). Same shape as `/networks/disconnect` — `"ed2k"` fires `EC_OP_SERVER_CONNECT`, `"kad"` fires `EC_OP_KAD_START`, omitted/`"both"` fires `EC_OP_CONNECT`.
+
+**Response:** `202 Accepted`.
+
+**Errors:** `400 bad_request` (unknown selector), `503 ec_unavailable`.
+
+#### `POST /api/v0/networks/disconnect`
+
+**Auth:** `ADMIN`
+
+**Body:** `{ "network": "ed2k" | "kad" | "both" }` (optional; defaults to `"both"`).
+
+**Response:** `200 OK`.
+
+**Errors:** `400 bad_request`, `503 ec_unavailable`.
+
+> Dedicated `POST /api/v0/kad/connect` and `POST /api/v0/kad/disconnect` shortcuts existed in an earlier draft of v0 but were dropped in favour of the `/networks/{connect,disconnect}` body selector — `{"network":"kad"}` does exactly what they did. The `/kad/bootstrap` endpoint below is genuinely distinct and stays.
+
+#### `POST /api/v0/kad/bootstrap`
+
+**Auth:** `ADMIN`
+
+Manual Kad bootstrap against a single known-good Kad node. Fires `EC_OP_KAD_BOOTSTRAP_FROM_IP` against amuled. This is the only Kad bootstrap surface the EC protocol exposes — `nodes.dat` is read by amuled at startup from its own data directory and is NOT manageable via REST.
+
+**Body:** `{ "ip": "203.0.113.5" | <uint32 host-order>, "port": <uint16> }`. `ip` accepts either the dotted-quad string form or the uint32 host-order integer form (amuled's wire-level shape). `port` is the contact's UDP port.
+
+```sh
+curl -s -X POST -H "Authorization: Bearer $TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d '{"ip":"203.0.113.5","port":4672}' \
+  "http://$HOST/api/v0/kad/bootstrap"
+```
+
+**Response:** `202 Accepted` → `{ "ok": true, "ip": <uint32>, "port": <uint16> }`. The Kad probe itself is fire-and-forget UDP; the `202` confirms amuled accepted the request, not that the contact was reachable.
+
+**Errors:** `400 bad_request` (missing/non-string-or-number `ip`, missing/non-numeric `port`, port outside `[0, 65535]`, malformed dotted-quad), `400 amuled_rejected`, `503 ec_unavailable`.
+
+#### `GET /api/v0/kad`
+
+**Auth:** `GUEST`
+
+Standalone view of the Kad subtree from `/status`, plus the detail fields the status rollup omits (`firewalled_udp`, `in_lan_mode`, your external `ip`, the `indexed` Kad-store counters, and `buddy` contact info for low-ID peers).
+
+```json
+{
+  "state": "connected",
+  "firewalled": false,
+  "firewalled_udp": false,
+  "in_lan_mode": false,
+  "ip": "203.0.113.5",
+  "network": { "users": 5400000, "files": 1400000000, "nodes": 2400 },
+  "indexed": { "sources": 12000, "keywords": 8500, "notes": 0, "load": 14 },
+  "buddy": { "status": "connected", "ip": "203.0.113.9", "port": 4672 }
+}
+```
+
+---
+
+### Logs
+
+#### `GET /api/v0/logs/amule`
+
+**Auth:** `GUEST`
+
+amuled's general log buffer.
+
+**Query parameters:** `tail=N` — return only the last N lines (default: full buffer).
+
+```json
+{
+  "lines": ["2026-06-19 11:00:00: line one", "...line two"],
+  "total_cached": 1024,
+  "returned": 2
+}
+```
+
+`lines` is the array of log lines; `total_cached` is how many lines are held in the buffer and `returned` how many this response carried (≤ `tail`).
+
+#### `DELETE /api/v0/logs/amule`
+
+**Auth:** `ADMIN`
+
+Clears the buffer.
+
+```json
+{ "ok": true }
+```
+
+#### `GET /api/v0/logs/serverinfo` / `DELETE /api/v0/logs/serverinfo`
+
+**Auth:** `GUEST` / `ADMIN`
+
+The ed2k server-info log buffer. Unlike `/logs/amule`, amuled ships this one as a single accumulated text blob, so the GET returns a `text` **string** rather than a `lines` array. `?tail=N` still selects by trailing lines (it walks back N newline boundaries), but the byte counts in the response describe the result.
+
+```json
+{
+  "text": "Connecting to eMule Server (203.0.113.5:4242)\nConnection established\n",
+  "total_bytes": 4096,
+  "returned_bytes": 68
+}
+```
+
+`DELETE /api/v0/logs/serverinfo` clears the buffer and returns `{ "ok": true }`.
+
+---
+
+### Statistics
+
+#### `GET /api/v0/stats/tree`
+
+**Auth:** `GUEST`
+
+A tree mirroring amuled's "Statistics" tree (transfers, connections, clients, servers, downloads). Cached with a 1 s TTL.
+
+The envelope is `{ "nodes": [...] }`. Each node is `{ "label": "<text>", "children": [...] }`; a leaf is a node whose `children` array is empty, with its value baked into the `label` string (e.g. `"Total uploaded: 12.4 GB"`).
+
+```json
+{
+  "nodes": [
+    {
+      "label": "Transfers",
+      "children": [
+        {
+          "label": "Uploads",
+          "children": [
+            { "label": "Total uploaded: 12.4 GB", "children": [] }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Errors:** `503 ec_unavailable`.
+
+#### `GET /api/v0/stats/graphs/{graph}`
+
+**Auth:** `GUEST`
+
+Time-series points behind the desktop Statistics graphs.
+
+`{graph}` is one of `download`, `upload`, `connections`, `kad`.
+
+**Query parameters:** `width=N` — clamp the response to the last `N` samples (default/`0` returns the full ~1800-sample window).
+
+```json
+{
+  "graph": "download",
+  "unit": "bps",
+  "interval_seconds": 1,
+  "points": [
+    { "t": "2026-06-19T11:00:00Z", "t_unix": 1781430000, "value": 4500000 },
+    { "t": "2026-06-19T11:00:10Z", "t_unix": 1781430010, "value": 4800000 }
+  ],
+  "session": { "download_bytes": 12400000000, "upload_bytes": 980000000, "kad_bytes": 5400000 }
+}
+```
+
+Each point is an object with `t` (ISO-8601 UTC), `t_unix` (unix seconds), and `value`. `unit` is `"bps"` for download/upload and `"count"` for connections/kad. `session` carries this-session byte totals so a client doesn't need a separate roundtrip.
+
+**Errors:** `404 not_found` (unknown graph name), `503 ec_unavailable`.
+
+---
+
+### Search
+
+The search surface is admin-only because firing a global ed2k search has real network cost.
+
+#### `POST /api/v0/search`
+
+**Auth:** `ADMIN`
+
+Kicks off a new search; the prior search results are wiped.
+
+**Body:**
+
+```json
+{
+  "query":     "ubuntu desktop iso",
+  "type":      "global",
+  "file_type": "iso",
+  "extension": "iso",
+  "min_size":  1000000000,
+  "max_size":  5000000000,
+  "min_avail": 5
+}
+```
+
+Only `query` is required. `type` defaults to `"global"`; valid values are `"local"`, `"global"`, `"kad"`.
+
+**Response:** `202 Accepted` → `{ "ok": true, "query": "..." }`.
+
+#### `GET /api/v0/search/results`
+
+**Auth:** `GUEST`
+
+Returns the current search-results buffer at the moment of the call PLUS a progress envelope so an empty `results` array isn't ambiguous between "no search running", "search in flight with no hits yet", and "search finished with zero hits".
+
+This endpoint does NOT busy-wait — it returns whatever amuled has in its result buffer right now. A client that wants to wait for completion should poll while `progress.state == "running"`. There is no per-GET TTL cache: `POST /search` marks the search active and the refresher polls amuled (`EC_OP_SEARCH_RESULTS` + `EC_OP_SEARCH_PROGRESS`) every tick while it stays active, so this GET reads straight from that refresher-maintained snapshot — successive polls see the growing result set with no extra EC roundtrip, and `POST /search/stop` simply clears the active flag.
+
+```json
+{
+  "results": [
+    {
+      "hash":         "8b54a3c2...",
+      "name":         "example-distribution-26.04-amd64.iso",
+      "size":         3825205248,
+      "sources":      { "total": 217, "complete": 142 },
+      "already_have": false,
+      "rating":       0
+    }
+  ],
+  "progress": {
+    "state":    "running",
+    "kind":     "kad",
+    "percent":  67
+  }
+}
+```
+
+Each result carries `sources` as a nested `{total, complete}` object — `total` is the swarm size amuled reports and `complete` is how many of those hold the file complete. `already_have` is `true` when the hash is already in your downloads/shared. `rating` is amuled's aggregated quality rating (`0` when unrated).
+
+The `progress` object carries the same `state` / `kind` / `percent` fields as the [`search_progress`](EVENTS.md#search_progress) SSE event, so REST pollers and stream consumers interpret progress identically. (The event additionally carries a `results` count, since — unlike this response — it has no `results` array beside it.)
+
+- `state` — `"running"` while the search is in flight, `"finished"` once amuled reports completion, `"idle"` when no search has run this session. This single field is canonical and replaces the older `complete` / `active` booleans (derive them as `complete = state == "finished"`, `active = state == "running"`).
+- `kind` — the originally-requested search type (`"local"` | `"global"` | `"kad"`).
+- `percent` — `[0, 100]`, computed by amuled for every search kind from its `EC_TAG_SEARCH_LIFECYCLE_PERCENT` tag. For **global** it is the real server-queue progress. For **Kad** — which has no measurable mid-flight progress — it is a cosmetic time-ramp off the fixed 45 s keyword-search lifetime, capped at 99 until amuled authoritatively reports completion (`EC_TAG_SEARCH_LIFECYCLE_STATE` = finished), at which point it snaps to 100. Treat the Kad value as a liveliness indicator, not an accurate estimate.
+
+A client that wants to wait for completion polls while `state == "running"`. Because amuled now reports the lifecycle state directly (no sentinel decode), `state == "running"` unambiguously means in-flight even for Kad — there is no longer any "is `percent: 0` a stalled Kad search or no search at all?" ambiguity; check `state` instead. A Kad search that hits its result cap (`SEARCHKEYWORD_TOTAL`, 300) before the 45 s deadline finishes early — `state` flips to `finished` and `percent` jumps to 100 ahead of the ramp.
+
+**Errors:** `503 ec_unavailable`.
+
+#### `POST /api/v0/search/stop`
+
+**Auth:** `ADMIN`
+
+Cancels the in-flight search; cached results stay.
+
+```json
+{ "ok": true }
+```
+
+#### `POST /api/v0/search/results/{hash}/download`
+
+**Auth:** `ADMIN`
+
+Promote a search result into the transfer queue. Equivalent to clicking "Download" on a desktop search row.
+
+**Body:** `{ "category": 0 }` (optional).
+
+**Response:** `202 Accepted` → `{ "ok": true, "hash": "...", "category": 0 }`.
+
+---
+
+## Error code catalog
+
+Every error code emitted by `/api/v0/*`, sorted by what triggered it. The matching HTTP status is in parentheses.
+
+| Code | Status | Meaning |
+|------|--------|---------|
+| `method_not_allowed` | 405 | Wrong HTTP verb for the route. |
+| `bad_request` | 400 | Body, query, or path-segment validation failed. Body parse depth-cap rejects also surface here. |
+| `unauthorized` | 401 | Missing token, bad signature, expired, revoked, or `iat` invariants failed. |
+| `invalid_credentials` | 401 | `/auth/login` password didn't match any role. |
+| `forbidden` | 403 | Authenticated as `guest` but the endpoint requires `admin`. |
+| `not_found` | 404 | Resource doesn't exist (unknown hash, ECID, graph name). |
+| `rate_limited` | 429 | Per-IP failure bucket full. `Retry-After: <seconds>` accompanies the response. |
+| `login_disabled` | 503 | `/auth/login` reached but no admin AND no guest password configured. |
+| `ec_unavailable` | 503 | EC connection not ready yet (cold start, transient amuled restart). |
+| `amuled_rejected` | 400 | amuled rejected the EC operation; the message field carries amuled's reason verbatim. |
+| `internal` | 500 | Handler threw. The body is generic; details land in the daemon's stderr. |
+
+`message` is human-readable and may change between releases. Pin on `code`.
+
+## Backward compatibility
+
+`/api/v0/` is frozen against any breaking change. Endpoints may add new fields to response bodies and new optional fields to request bodies; clients SHOULD ignore unknown fields. Renaming, removing, or tightening a field's type is a v1 affair.
+
+`POST /api/v0/auth/login`'s default body shape (no token unless `?type=bearer`) IS a change from the very first amuleapi cuts; the legacy "token always in body" behaviour is reachable only via the opt-in. This is documented and committed.
diff --git a/docs/man/CMakeLists.txt b/docs/man/CMakeLists.txt
index b1457c2493..befa9409fc 100644
--- a/docs/man/CMakeLists.txt
+++ b/docs/man/CMakeLists.txt
@@ -27,6 +27,10 @@ if (BUILD_WEBSERVER)
 	check_manpage ("amuleweb")
 endif()
 
+if (BUILD_AMULEAPI)
+	check_manpage ("amuleapi")
+endif()
+
 # Translated manpages — rendered at build time via po4a from the English
 # masters plus po/manpages-<lang>.po. The rendered files are not tracked in
 # git; po4a writes them straight into the build dir based on absolute paths
@@ -65,6 +69,16 @@ if (TRANSLATED_MANPAGES)
 		# Per-binary install destination + build-system gate. The util
 		# binaries have their rendered outputs land in their own build
 		# subdirs because po4a.config.in points them there explicitly.
+		#
+		# amuleapi is INTENTIONALLY absent from this list: the English
+		# master ships (gated by BUILD_AMULEAPI in the top-half
+		# check_manpage() block above), but the po4a translation
+		# pipeline has no amuleapi strings in po/manpages-*.po yet, so
+		# adding amuleapi here would break the build by asking po4a to
+		# render a translation it has no source for. English-only
+		# until 3.1; the translator workflow lands amuleapi entries in
+		# po/manpages-*.po, which adds amuleapi to MANPAGE_BINARIES +
+		# MANPAGE_GATE_amuleapi BUILD_AMULEAPI here.
 		set (MANPAGE_BINARIES amule amulecmd amuled amulegui amuleweb ed2k alc alcc cas wxcas)
 		set (MANPAGE_BUILD_DIR_amule     "${CMAKE_CURRENT_BINARY_DIR}")
 		set (MANPAGE_BUILD_DIR_amulecmd  "${CMAKE_CURRENT_BINARY_DIR}")
diff --git a/docs/man/amuleapi.1.in b/docs/man/amuleapi.1.in
new file mode 100644
index 0000000000..565c53e108
--- /dev/null
+++ b/docs/man/amuleapi.1.in
@@ -0,0 +1,111 @@
+.TH AMULEAPI 1 @MAN_DATE@ "aMule REST API daemon v@PACKAGE_VERSION@" "aMule REST API daemon"
+.als B_untranslated B
+.als RB_untranslated RB
+.SH NAME
+amuleapi \- the aMule REST API + Server\-Sent Events daemon
+.SH SYNOPSIS
+.B_untranslated amuleapi
+.RB [ \-h " " \fI<host> ]
+.RB [ \-p " " \fI<port> ]
+.RB [ \-P " " \fI<password> ]
+.RB_untranslated [ \-\-bind " " \fI<address> ]
+.RB_untranslated [ \-\-http\-port " " \fI<num> ]
+.RB_untranslated [ \-\-config\-dir " " \fI<path> ]
+.RB_untranslated [ \-\-foreground ]
+
+.B_untranslated amuleapi
+.RB_untranslated [ \-\-set\-admin\-pass " " \fI<plain> ]
+
+.B_untranslated amuleapi
+.RB_untranslated [ \-\-set\-guest\-pass " " \fI<plain> ]
+
+.B_untranslated amuleapi
+.RB_untranslated [ \-\-version ]
+
+.B_untranslated amuleapi
+.RB_untranslated [ \-\-help ]
+.SH DESCRIPTION
+.B_untranslated amuleapi
+is a standalone HTTP daemon that exposes a versioned JSON REST API and a
+long\-lived Server\-Sent Events stream backed by a single
+\fBamuled\fR(1) instance over the EC protocol. It is intended to run
+alongside \fBamuled\fR (which it connects to as an EC client) and serves
+its HTTP surface on a separate port from \fBamuleweb\fR(1) \- the two
+can run concurrently against the same daemon.
+.PP
+The wire contract for the REST API is documented at
+\fIdocs/api/REFERENCE.md\fR; the SSE event catalog lives at
+\fIdocs/api/EVENTS.md\fR. See \fIdocs/QUICKSTART\-AMULEAPI.md\fR
+for first\-run setup notes.
+.SH OPTIONS
+.TP
+\fB[ \-h\fR \fI<host>\fR, \fB\-\-host\fR=\fI<host>\fR \fB]\fR
+EC host to connect to (default: 127.0.0.1).
+.TP
+\fB[ \-p\fR \fI<port>\fR, \fB\-\-port\fR=\fI<port>\fR \fB]\fR
+EC port on the amuled instance (default: 4712).
+.TP
+\fB[ \-P\fR \fI<password>\fR, \fB\-\-password\fR=\fI<password>\fR \fB]\fR
+EC plaintext password (matches amuled's [ExternalConnect]/Password).
+.TP
+\fB[ \-\-bind\fR=\fI<address>\fR \fB]\fR
+HTTP bind address (default: 127.0.0.1, overrides amuleapi.conf
+[Server]/BindAddress).
+.TP
+\fB[ \-\-http\-port\fR=\fI<num>\fR \fB]\fR
+HTTP listen port (default: 4713, overrides amuleapi.conf
+[Server]/Port).
+.TP
+\fB[ \-\-config\-dir\fR=\fI<path>\fR \fB]\fR
+Path to the amuleapi config dir. Defaults to the same per\-platform
+aMule data directory that \fBamuled\fR uses (~/.aMule/ on Linux,
+~/Library/Application Support/aMule/ on macOS, %APPDATA%\\aMule\\ on
+Windows). Creates the dir with mode 0700 if absent.
+.TP
+\fB[ \-\-set\-admin\-pass\fR=\fI<plain>\fR \fB]\fR
+Hash \fI<plain>\fR with MD5 and store it as the admin password in
+\fIamuleapi\-passwords\fR (mode 0600), then exit. Does not start the
+HTTP server or connect to amuled.
+.TP
+\fB[ \-\-set\-guest\-pass\fR=\fI<plain>\fR \fB]\fR
+Hash \fI<plain>\fR with MD5 and store it as the guest password in
+\fIamuleapi\-passwords\fR (mode 0600), then exit.
+.TP
+\fB[ \-\-foreground ]\fR
+Stay in the foreground (default). aMule does not ship init\-system
+units; if you need a system service wrapper, write a downstream unit
+that wraps the foreground command.
+.TP
+\fB[ \-\-version ]\fR
+Print version information and exit.
+.TP
+\fB[ \-\-help ]\fR
+Print a short usage description.
+.SH FILES
+.TP
+\fI~/.aMule/amuleapi.conf\fR
+INI\-style runtime config: \fB[Server]\fR (bind address, HTTP port, CORS
+allowlist), \fB[EC]\fR (outbound connection to amuled), \fB[Auth]\fR (login
+rate\-limit knobs), \fB[Streaming]\fR (SSE event\-bus ring capacity). The
+QUICKSTART document distributed with the source has the full
+reference.
+.TP
+\fI~/.aMule/amuleapi\-jwt\-secret\fR
+32\-byte HMAC signing key for issued tokens. Mode 0600. Auto\-generated
+on first launch if absent. Deleting the file invalidates every
+previously\-issued token.
+.TP
+\fI~/.aMule/amuleapi\-passwords\fR
+INI\-style MD5\-hashed admin + guest passwords. Mode 0600. Written via
+\fB\-\-set\-admin\-pass\fR / \fB\-\-set\-guest\-pass\fR.
+.SH REPORTING BUGS
+Please report bugs either on our forum
+(\fIhttps://github.com/amule-org/amule/discussions\fR), or in our
+bugtracker (\fIhttps://github.com/amule-org/amule/issues\fR).
+.SH COPYRIGHT
+aMule and all of its related utilities are distributed under the GNU
+General Public License.
+.SH SEE ALSO
+.B_untranslated amule\fR(1), \fBamuled\fR(1), \fBamulecmd\fR(1), \fBamuleweb\fR(1)
+.SH AUTHOR
+This manpage was written for the aMule project.
diff --git a/packaging/flathub/org.amule.aMule.yaml b/packaging/flathub/org.amule.aMule.yaml
index eb91e63dfe..11c23fe1af 100644
--- a/packaging/flathub/org.amule.aMule.yaml
+++ b/packaging/flathub/org.amule.aMule.yaml
@@ -234,6 +234,7 @@ modules:
       - -DBUILD_REMOTEGUI=YES
       - -DBUILD_DAEMON=YES
       - -DBUILD_AMULECMD=YES
+      - -DBUILD_AMULEAPI=YES
       - -DBUILD_ED2K=YES
       - -DBUILD_WEBSERVER=YES
       - -DBUILD_CAS=YES
diff --git a/packaging/linux/appimage/AppRun b/packaging/linux/appimage/AppRun
index 1368aa066e..5d16d638a0 100644
--- a/packaging/linux/appimage/AppRun
+++ b/packaging/linux/appimage/AppRun
@@ -2,7 +2,7 @@
 # Custom AppRun for the aMule AppImage.
 #
 # Dispatches to one of the bundled binaries (amule / amuled / amulegui /
-# amulecmd / amuleweb / ed2k) based on the name the AppImage was invoked
+# amulecmd / amuleweb / amuleapi / ed2k) based on the name the AppImage was invoked
 # as. The AppImage runtime sets $ARGV0 to the path used to launch the
 # image; basename of that gives us the symlink name. Standard idiom —
 # same pattern Krita and GIMP use to ship multiple tools in one bundle.
@@ -49,7 +49,7 @@ NAME="${NAME%-aarch64}"
 NAME="${NAME%-Linux}"
 
 case "${NAME}" in
-    amuled|amulegui|amulecmd|amuleweb|ed2k|cas|wxcas|alc|alcc)
+    amuled|amulegui|amulecmd|amuleweb|amuleapi|ed2k|cas|wxcas|alc|alcc)
         BIN="${HERE}/usr/bin/${NAME}"
         ;;
     *)
diff --git a/packaging/linux/appimage/build.sh b/packaging/linux/appimage/build.sh
index 618bb7ebf8..18be6c6070 100755
--- a/packaging/linux/appimage/build.sh
+++ b/packaging/linux/appimage/build.sh
@@ -40,6 +40,7 @@ cmake -B "${BUILD_DIR}" -S "${REPO}" -G Ninja \
     -DBUILD_REMOTEGUI=YES \
     -DBUILD_DAEMON=YES \
     -DBUILD_AMULECMD=YES \
+    -DBUILD_AMULEAPI=YES \
     -DBUILD_ED2K=YES \
     -DBUILD_WEBSERVER=YES \
     -DBUILD_CAS=YES \
@@ -66,7 +67,7 @@ DESTDIR="${APPDIR}" cmake --install "${BUILD_DIR}"
 #    invokes the daemon, amulegui invokes the remote GUI, and so on.
 #    Listing each via --executable makes linuxdeploy walk their .so
 #    deps and bundle every transitive library.
-EXTRA_BINS=(amuled amulegui amulecmd amuleweb ed2k cas wxcas alc alcc)
+EXTRA_BINS=(amuled amulegui amulecmd amuleweb amuleapi ed2k cas wxcas alc alcc)
 EXEC_ARGS=()
 for bin in "${EXTRA_BINS[@]}"; do
     if [ -x "${APPDIR}/usr/bin/${bin}" ]; then
diff --git a/packaging/linux/flatpak/org.amule.aMule.yaml.in b/packaging/linux/flatpak/org.amule.aMule.yaml.in
index 26ef5697f8..2a45620704 100644
--- a/packaging/linux/flatpak/org.amule.aMule.yaml.in
+++ b/packaging/linux/flatpak/org.amule.aMule.yaml.in
@@ -354,6 +354,7 @@ modules:
       - -DBUILD_REMOTEGUI=YES
       - -DBUILD_DAEMON=YES
       - -DBUILD_AMULECMD=YES
+      - -DBUILD_AMULEAPI=YES
       - -DBUILD_ED2K=YES
       - -DBUILD_WEBSERVER=YES
       - -DBUILD_CAS=YES
diff --git a/packaging/macos/build.sh b/packaging/macos/build.sh
index c9f597aeb0..154ca21791 100755
--- a/packaging/macos/build.sh
+++ b/packaging/macos/build.sh
@@ -79,6 +79,7 @@ build() {
         -DBUILD_REMOTEGUI=YES \
         -DBUILD_DAEMON=YES \
         -DBUILD_AMULECMD=YES \
+        -DBUILD_AMULEAPI=YES \
         -DBUILD_ED2K=YES \
         -DBUILD_WEBSERVER=YES \
         -DBUILD_CAS=YES \
@@ -118,6 +119,7 @@ build() {
         src/amuled
         src/amulecmd
         src/webserver/src/amuleweb
+        src/webapi/amuleapi
         src/ed2k
         src/utils/cas/cas
         src/utils/wxCas/src/wxcas
diff --git a/packaging/windows/build.sh b/packaging/windows/build.sh
index faf4a8906e..87e53ea0a1 100755
--- a/packaging/windows/build.sh
+++ b/packaging/windows/build.sh
@@ -99,6 +99,7 @@ build() {
         -DBUILD_REMOTEGUI=YES \
         -DBUILD_DAEMON=YES \
         -DBUILD_AMULECMD=YES \
+        -DBUILD_AMULEAPI=YES \
         -DBUILD_ED2K=YES \
         -DBUILD_WEBSERVER=YES \
         -DBUILD_CAS=YES \
diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt
index a7f6c12b6c..e64c906498 100644
--- a/src/CMakeLists.txt
+++ b/src/CMakeLists.txt
@@ -69,6 +69,16 @@ if (BUILD_WEBSERVER)
 	add_subdirectory (webserver)
 endif()
 
+# Pure-logic primitives (JWT / ETag / route patterns / JSON writer)
+# that the upcoming amuleapi binary and its unit tests link against.
+# Built unconditionally — no transitive cost for builds that don't
+# consume it (static lib, zero runtime overhead).
+add_subdirectory (libwebcommon)
+
+if (BUILD_AMULEAPI)
+	add_subdirectory (webapi)
+endif()
+
 if (INSTALL_SKINS)
 	add_subdirectory (skins)
 endif()
@@ -382,6 +392,25 @@ if (BUILD_MONOLITHIC)
 				)
 			endforeach()
 		endif()
+
+		# Mirror for amuleapi's static-frontend root. Resolves at
+		# runtime via LSCopyApplicationURLsForBundleIdentifier(
+		# "org.amule.aMule") + CFBundleCopyResourceURL("amuleapi-
+		# static"); see Api.cpp::ResolveDefaultStaticDir. Without this
+		# step a Mac user who installed via the .app bundle would get
+		# `404 no such endpoint` on GET / unless they hand-edited
+		# amuleapi.conf StaticRoot.
+		if (BUILD_AMULEAPI)
+			set (_apifs_src "${CMAKE_SOURCE_DIR}/src/webapi/static")
+			set (_apifs_dst
+				"$<TARGET_BUNDLE_CONTENT_DIR:amule>/Resources/amuleapi-static")
+			add_custom_command (TARGET amule POST_BUILD
+				COMMAND ${CMAKE_COMMAND} -E copy_directory
+					"${_apifs_src}" "${_apifs_dst}"
+				COMMENT "Bundling amuleapi static frontend into aMule.app"
+				VERBATIM
+			)
+		endif()
 	endif()
 
 	install (TARGETS amule
diff --git a/src/ExternalConn.cpp b/src/ExternalConn.cpp
index b05c45f078..46a674281c 100644
--- a/src/ExternalConn.cpp
+++ b/src/ExternalConn.cpp
@@ -2110,8 +2110,27 @@ CECPacket *CECServerSocket::ProcessRequest2(const CECPacket *request)
 
 		case EC_OP_SEARCH_PROGRESS:
 			response = new CECPacket(EC_OP_SEARCH_PROGRESS);
+			// EC_TAG_SEARCH_STATUS: unchanged overloaded sentinel for
+			// pre-3.1 consumers (amulegui / amuleweb / amulecmd) that
+			// already decode 0xffff / 0xfffe / 0..100.
 			response->AddTag(CECTag(EC_TAG_SEARCH_STATUS,
 				theApp->searchlist->GetSearchProgress()));
+			// New unambiguous lifecycle tags (3.1+). Modern consumers
+			// like amuleapi prefer these and skip the sentinel decode
+			// entirely. Absent from the response on pre-3.1 daemons —
+			// new consumers fall back to EC_TAG_SEARCH_STATUS in that
+			// case.
+			response->AddTag(CECTag(EC_TAG_SEARCH_LIFECYCLE_STATE,
+				static_cast<uint8>(theApp->searchlist->GetSearchLifecycleState())));
+			response->AddTag(CECTag(EC_TAG_SEARCH_LIFECYCLE_KIND,
+				static_cast<uint8>(theApp->searchlist->GetSearchLifecycleKind())));
+			response->AddTag(CECTag(EC_TAG_SEARCH_RESULT_COUNT,
+				static_cast<uint32>(theApp->searchlist->GetCurrentSearchResultCount())));
+			// Unified 0..100 completion. Global = real server-queue
+			// percent; Kad = cosmetic time-ramp (no measurable progress);
+			// FINISHED snaps any kind to 100. amuleapi reads this directly.
+			response->AddTag(CECTag(EC_TAG_SEARCH_LIFECYCLE_PERCENT,
+				static_cast<uint8>(theApp->searchlist->GetSearchLifecyclePercent())));
 			break;
 
 		case EC_OP_DOWNLOAD_SEARCH_RESULT:
diff --git a/src/SearchList.cpp b/src/SearchList.cpp
index de452ef33f..a718e7733d 100644
--- a/src/SearchList.cpp
+++ b/src/SearchList.cpp
@@ -51,6 +51,7 @@
 
 #include "kademlia/kademlia/Kademlia.h"
 #include "kademlia/kademlia/Search.h"
+#include "kademlia/kademlia/Defines.h"	// Needed for SEARCHKEYWORD_LIFETIME (Kad ramp)
 
 #include "SearchExpr.h"
 
@@ -274,7 +275,8 @@ CSearchList::CSearchList()
 	  m_currentSearch(-1),
 	  m_searchPacket(NULL),
 	  m_64bitSearchPacket(false),
-	  m_KadSearchFinished(true)
+	  m_KadSearchFinished(true),
+	  m_searchStart(0)
 {}
 
 
@@ -355,6 +357,7 @@ wxString CSearchList::StartNewSearch(uint32* searchID, SearchType type, CSearchP
 	}
 
 	m_searchType = type;
+	m_searchStart = time(NULL);
 
 	// EC clients reuse the sentinel `0xffffffff` for every search regardless
 	// of network type. `Get_EC_Response_Search` -> `RemoveResults(0xffffffff)`
@@ -449,6 +452,75 @@ uint32 CSearchList::GetSearchProgress() const
 }
 
 
+CSearchList::SearchLifecycleState CSearchList::GetSearchLifecycleState() const
+{
+	// m_currentSearch defaults to wxUIntPtr(-1); never reassigned until
+	// the first StartNewSearch. Distinguishes "never started" from
+	// "completed and reset" (the latter resets m_currentSearch to -1 too
+	// when m_searchType == GlobalSearch in StopSearch).
+	if (m_currentSearch == wxUIntPtr(-1)) {
+		return SEARCH_LIFECYCLE_IDLE;
+	}
+	if (m_searchType == KadSearch) {
+		return m_KadSearchFinished ? SEARCH_LIFECYCLE_FINISHED
+		                           : SEARCH_LIFECYCLE_RUNNING;
+	}
+	// ED2K (Local / Global): m_searchInProgress is the source of truth.
+	return m_searchInProgress ? SEARCH_LIFECYCLE_RUNNING
+	                          : SEARCH_LIFECYCLE_FINISHED;
+}
+
+
+std::size_t CSearchList::GetCurrentSearchResultCount() const
+{
+	if (m_currentSearch == wxUIntPtr(-1)) return 0;
+	ResultMap::const_iterator it = m_results.find(m_currentSearch);
+	return (it == m_results.end()) ? 0 : it->second.size();
+}
+
+
+uint8 CSearchList::GetSearchLifecyclePercent() const
+{
+	switch (GetSearchLifecycleState()) {
+		case SEARCH_LIFECYCLE_IDLE:
+			return 0;
+		case SEARCH_LIFECYCLE_FINISHED:
+			// Authoritative completion edge for every search kind.
+			return 100;
+		case SEARCH_LIFECYCLE_RUNNING:
+			break;
+	}
+
+	// --- RUNNING ---
+	if (m_searchType == KadSearch) {
+		// Kad has no measurable progress (see GetSearchProgress: the
+		// daemon can only tell us *that* it ended, not how far along it
+		// is). Synthesise a cosmetic ramp from the fixed keyword-search
+		// lifetime so consumers get a moving bar. Capped at 99 — the
+		// FINISHED state above is what snaps it to 100, so the ramp can
+		// never claim completion before the daemon actually does. An
+		// early finish (SEARCHKEYWORD_TOTAL results before the deadline)
+		// likewise flips to FINISHED and jumps the bar to 100.
+		time_t elapsed = time(NULL) - m_searchStart;
+		if (elapsed <= 0) {
+			return 0;
+		}
+		uint32 pct = (uint32)((elapsed * 100) / SEARCHKEYWORD_LIFETIME);
+		return (pct > 99) ? 99 : (uint8)pct;
+	}
+
+	if (m_searchType == GlobalSearch) {
+		// Real server-queue-driven percent (0..100).
+		uint32 pct = GetSearchProgress();
+		return (pct > 100) ? 100 : (uint8)pct;
+	}
+
+	// LocalSearch is instantaneous and never observed RUNNING here; if it
+	// somehow is, we have no sub-step granularity to report.
+	return 0;
+}
+
+
 void CSearchList::OnGlobalSearchTimer(CTimerEvent& WXUNUSED(evt))
 {
 	// Ensure that the server-queue contains the current servers.
diff --git a/src/SearchList.h b/src/SearchList.h
index bd4d364298..6b78cae43f 100644
--- a/src/SearchList.h
+++ b/src/SearchList.h
@@ -110,6 +110,27 @@ class CSearchList : public wxEvtHandler
 	/** Returns the completion percentage of the current search. */
 	uint32 GetSearchProgress() const;
 
+	// Unambiguous lifecycle accessors used by the new EC tags
+	// (EC_TAG_SEARCH_LIFECYCLE_STATE / _KIND / _RESULT_COUNT). Old
+	// consumers still read the overloaded GetSearchProgress() return.
+	enum SearchLifecycleState {
+		SEARCH_LIFECYCLE_IDLE     = 0,  // no search started this session
+		SEARCH_LIFECYCLE_RUNNING  = 1,  // active search in flight
+		SEARCH_LIFECYCLE_FINISHED = 2   // last search completed; results retained
+	};
+	SearchLifecycleState GetSearchLifecycleState() const;
+	// Echoes m_searchType for the current/last search; meaningful only
+	// when state is RUNNING or FINISHED. Returns LocalSearch by default.
+	SearchType           GetSearchLifecycleKind()  const { return m_searchType; }
+	// Result count for the current search; 0 if idle.
+	std::size_t          GetCurrentSearchResultCount() const;
+	// Unified 0..100 completion for the current search, surfaced via
+	// EC_TAG_SEARCH_LIFECYCLE_PERCENT. Global uses the real server-queue
+	// percent; Kad — which has no measurable progress — gets a cosmetic
+	// time-ramp off the fixed keyword-search lifetime that the FINISHED
+	// lifecycle state authoritatively snaps to 100. Idle returns 0.
+	uint8                GetSearchLifecyclePercent() const;
+
 	/** This function is called once the local (ed2k) search has ended. */
 	void	LocalSearchEnd();
 
@@ -225,6 +246,11 @@ class CSearchList : public wxEvtHandler
 	//! If the current search is a KAD search this signals if it is finished.
 	bool		m_KadSearchFinished;
 
+	//! Wall-clock start of the current/last search. Stamped in
+	//! StartNewSearch; feeds the Kad cosmetic progress ramp in
+	//! GetSearchLifecyclePercent.
+	time_t		m_searchStart;
+
 	//! Queue of servers to ask when doing global searches.
 	//! TODO: Replace with 'cookie' system.
 	CQueueObserver<CServer*> m_serverQueue;
diff --git a/src/libs/ec/abstracts/ECCodes.abstract b/src/libs/ec/abstracts/ECCodes.abstract
index 65068560d3..62d73f0665 100644
--- a/src/libs/ec/abstracts/ECCodes.abstract
+++ b/src/libs/ec/abstracts/ECCodes.abstract
@@ -335,6 +335,10 @@ EC_TAG_SEARCHFILE                         0x0700
 	EC_TAG_SEARCH_AVAILABILITY                0x0707
 	EC_TAG_SEARCH_STATUS                      0x0708
 	EC_TAG_SEARCH_PARENT                      0x0709
+	EC_TAG_SEARCH_LIFECYCLE_STATE             0x070A
+	EC_TAG_SEARCH_LIFECYCLE_KIND              0x070B
+	EC_TAG_SEARCH_RESULT_COUNT                0x070C
+	EC_TAG_SEARCH_LIFECYCLE_PERCENT           0x070D
 
 EC_TAG_FRIEND                             0x0800
 	EC_TAG_FRIEND_NAME                        0x0801
diff --git a/src/libs/ec/cpp/ECCodes.h b/src/libs/ec/cpp/ECCodes.h
index aedbdadb57..d2f729df24 100644
--- a/src/libs/ec/cpp/ECCodes.h
+++ b/src/libs/ec/cpp/ECCodes.h
@@ -297,6 +297,15 @@ enum ECTagNames {
 		EC_TAG_SEARCH_AVAILABILITY                = 0x0707,
 		EC_TAG_SEARCH_STATUS                      = 0x0708,
 		EC_TAG_SEARCH_PARENT                      = 0x0709,
+		// Unambiguous lifecycle tags on EC_OP_SEARCH_PROGRESS responses
+		// (3.1+). Old clients keep reading EC_TAG_SEARCH_STATUS unchanged;
+		// new clients (amuleapi) prefer these and skip the overloaded
+		// sentinel decode in CSearchList::GetSearchProgress.
+		EC_TAG_SEARCH_LIFECYCLE_STATE             = 0x070A,
+		EC_TAG_SEARCH_LIFECYCLE_KIND              = 0x070B,
+		EC_TAG_SEARCH_RESULT_COUNT                = 0x070C,
+		// Unified 0..100 percent (global = real, Kad = cosmetic ramp).
+		EC_TAG_SEARCH_LIFECYCLE_PERCENT           = 0x070D,
 	EC_TAG_FRIEND                             = 0x0800,
 		EC_TAG_FRIEND_NAME                        = 0x0801,
 		EC_TAG_FRIEND_HASH                        = 0x0802,
@@ -754,6 +763,10 @@ wxString GetDebugNameECTagNames(uint16 arg)
 		case 0x0707: return "EC_TAG_SEARCH_AVAILABILITY";
 		case 0x0708: return "EC_TAG_SEARCH_STATUS";
 		case 0x0709: return "EC_TAG_SEARCH_PARENT";
+		case 0x070A: return "EC_TAG_SEARCH_LIFECYCLE_STATE";
+		case 0x070B: return "EC_TAG_SEARCH_LIFECYCLE_KIND";
+		case 0x070C: return "EC_TAG_SEARCH_RESULT_COUNT";
+		case 0x070D: return "EC_TAG_SEARCH_LIFECYCLE_PERCENT";
 		case 0x0800: return "EC_TAG_FRIEND";
 		case 0x0801: return "EC_TAG_FRIEND_NAME";
 		case 0x0802: return "EC_TAG_FRIEND_HASH";
diff --git a/src/libs/ec/java/ECCodes.java b/src/libs/ec/java/ECCodes.java
index d480103659..5bf54f5f27 100644
--- a/src/libs/ec/java/ECCodes.java
+++ b/src/libs/ec/java/ECCodes.java
@@ -280,6 +280,10 @@ public interface ECCodes {
 public final static short 	EC_TAG_SEARCH_AVAILABILITY                = 0x0707;
 public final static short 	EC_TAG_SEARCH_STATUS                      = 0x0708;
 public final static short 	EC_TAG_SEARCH_PARENT                      = 0x0709;
+public final static short 	EC_TAG_SEARCH_LIFECYCLE_STATE             = 0x070A;
+public final static short 	EC_TAG_SEARCH_LIFECYCLE_KIND              = 0x070B;
+public final static short 	EC_TAG_SEARCH_RESULT_COUNT                = 0x070C;
+public final static short 	EC_TAG_SEARCH_LIFECYCLE_PERCENT           = 0x070D;
 public final static short EC_TAG_FRIEND                             = 0x0800;
 public final static short 	EC_TAG_FRIEND_NAME                        = 0x0801;
 public final static short 	EC_TAG_FRIEND_HASH                        = 0x0802;
diff --git a/src/libwebcommon/CMakeLists.txt b/src/libwebcommon/CMakeLists.txt
new file mode 100644
index 0000000000..450229e5be
--- /dev/null
+++ b/src/libwebcommon/CMakeLists.txt
@@ -0,0 +1,31 @@
+# libwebcommon — pure-logic primitives for the amuleapi REST surface.
+#
+# Linked into the amuleapi binary and the libwebcommon unit-test
+# target. NOT linked into amuleweb: amuleweb's behaviour on 3.0.x is
+# bit-identical to 3.0.0 and is built from the same translation units
+# it always was. If a downstream consumer (e.g. a hypothetical
+# integration test or a third-party amule front-end) wants the same
+# JWT / ETag / route-pattern primitives, link against this lib too.
+
+add_library (webcommon STATIC
+	ConstantTime.cpp
+	Etag.cpp
+	HeaderParse.cpp
+	JsonWriter.cpp
+	Jwt.cpp
+	PathPatterns.cpp
+)
+
+target_include_directories (webcommon
+	PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}
+)
+
+# wxWidgets::BASE for wxString (used by JsonWriter + ConstantTime).
+# No GUI dependency — these are wxBase-only types. CRYPTOPP::CRYPTOPP
+# carries its own INTERFACE_INCLUDE_DIRECTORIES so consumers get
+# <cryptopp/sha.h> / <cryptopp/hmac.h> visible without further
+# include-path wiring.
+target_link_libraries (webcommon
+	PUBLIC wxWidgets::BASE
+	PUBLIC CRYPTOPP::CRYPTOPP
+)
diff --git a/src/libwebcommon/ConstantTime.cpp b/src/libwebcommon/ConstantTime.cpp
new file mode 100644
index 0000000000..d14e765d0c
--- /dev/null
+++ b/src/libwebcommon/ConstantTime.cpp
@@ -0,0 +1,49 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#include "ConstantTime.h"
+
+
+namespace webcommon {
+
+bool ConstantTimeEquals(const std::string &a, const std::string &b)
+{
+	if (a.size() != b.size()) return false;
+	unsigned char acc = 0;
+	for (size_t i = 0; i < a.size(); ++i) {
+		acc |= static_cast<unsigned char>(a[i] ^ b[i]);
+	}
+	return acc == 0;
+}
+
+bool ConstantTimeEquals(const wxString &a, const wxString &b)
+{
+	const wxScopedCharBuffer au = a.utf8_str();
+	const wxScopedCharBuffer bu = b.utf8_str();
+	return ConstantTimeEquals(
+		std::string(au.data(), au.length()),
+		std::string(bu.data(), bu.length()));
+}
+
+}  // namespace webcommon
diff --git a/src/libwebcommon/ConstantTime.h b/src/libwebcommon/ConstantTime.h
new file mode 100644
index 0000000000..37e0999d68
--- /dev/null
+++ b/src/libwebcommon/ConstantTime.h
@@ -0,0 +1,54 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#ifndef LIBWEBCOMMON_CONSTANTTIME_H
+#define LIBWEBCOMMON_CONSTANTTIME_H
+
+#include <string>
+
+#include <wx/string.h>
+
+
+// XOR-accumulator constant-time equality. Returns false immediately
+// on length mismatch (length is not the secret); for equal-length
+// inputs the timing is data-independent.
+//
+// **PRECONDITION on the `wxString` overload.** wxString is a UTF-16
+// or UTF-32 sequence depending on the build; the comparator checks
+// sequence length first, not byte length. Inputs that round-trip
+// through different UTF-8 encodings and share an underlying string
+// but differ in codepoint count will short-circuit as unequal.
+// Callers today compare fixed-shape inputs (32-char hex MD5,
+// 43-char base64url HMAC) so the precondition holds. Length-
+// variable callers MUST pad to a common bound first or accept a
+// length-side-channel leak.
+
+namespace webcommon {
+
+bool ConstantTimeEquals(const std::string &a, const std::string &b);
+bool ConstantTimeEquals(const wxString   &a, const wxString   &b);
+
+}  // namespace webcommon
+
+#endif // LIBWEBCOMMON_CONSTANTTIME_H
diff --git a/src/libwebcommon/Etag.cpp b/src/libwebcommon/Etag.cpp
new file mode 100644
index 0000000000..86f11114ef
--- /dev/null
+++ b/src/libwebcommon/Etag.cpp
@@ -0,0 +1,100 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#include "Etag.h"
+
+#include <cryptopp/sha.h>
+
+
+namespace webcommon {
+
+
+std::string Etag(const std::string &body_utf8)
+{
+	CryptoPP::SHA256 sha;
+	unsigned char digest[CryptoPP::SHA256::DIGESTSIZE];
+	sha.CalculateDigest(digest,
+		reinterpret_cast<const unsigned char *>(body_utf8.data()),
+		body_utf8.size());
+	static const char hex[] = "0123456789abcdef";
+	std::string out;
+	out.reserve(16);
+	for (int i = 0; i < 8; ++i) {
+		out.push_back(hex[(digest[i] >> 4) & 0x0F]);
+		out.push_back(hex[ digest[i]       & 0x0F]);
+	}
+	return out;
+}
+
+
+// Strip leading/trailing whitespace + optional `W/` weak-validator
+// prefix + optional outer double quotes from one If-None-Match
+// entry (RFC 7232 §3.2 + §2.3). Weak and strong validators with the
+// same opaque payload compare equal for 304 purposes; we don't
+// carry a separate weak/strong dimension on the response side.
+static std::string NormalizeOneValidator(const std::string &raw)
+{
+	std::size_t start = 0;
+	std::size_t end   = raw.size();
+	while (start < end &&
+	       (raw[start] == ' ' || raw[start] == '\t')) ++start;
+	while (end > start &&
+	       (raw[end - 1] == ' ' || raw[end - 1] == '\t')) --end;
+	// Strip weak-validator prefix `W/` (case-sensitive per RFC).
+	if (end - start >= 2 && raw[start] == 'W' && raw[start + 1] == '/') {
+		start += 2;
+	}
+	// Strip outer double quotes if both present.
+	if (end - start >= 2 && raw[start] == '"' && raw[end - 1] == '"') {
+		++start;
+		--end;
+	}
+	return raw.substr(start, end - start);
+}
+
+
+bool IfNoneMatchHits(const std::string &if_none_match,
+                     const std::string &etag)
+{
+	if (if_none_match.empty()) return false;
+	// Header value may be a single validator or a comma-separated
+	// list — walk it, normalise each entry, return true on any hit.
+	// `*` matches any existing representation; the caller only
+	// invokes this on a 200-with-body, so `*` is always a hit.
+	std::size_t pos = 0;
+	while (pos <= if_none_match.size()) {
+		const std::size_t comma = if_none_match.find(',', pos);
+		const std::size_t end   = (comma == std::string::npos)
+			? if_none_match.size() : comma;
+		const std::string entry = NormalizeOneValidator(
+			if_none_match.substr(pos, end - pos));
+		if (entry == "*" || entry == etag) return true;
+		if (comma == std::string::npos) break;
+		pos = comma + 1;
+	}
+	return false;
+}
+
+
+}  // namespace webcommon
diff --git a/src/libwebcommon/Etag.h b/src/libwebcommon/Etag.h
new file mode 100644
index 0000000000..25650048d5
--- /dev/null
+++ b/src/libwebcommon/Etag.h
@@ -0,0 +1,70 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#ifndef LIBWEBCOMMON_ETAG_H
+#define LIBWEBCOMMON_ETAG_H
+
+#include <string>
+
+
+// ETag computation + If-None-Match comparison for the REST API.
+// Single source of truth for the digest-truncation rule — every
+// binary uses the same algorithm so client caches stay valid
+// across daemons.
+
+namespace webcommon {
+
+
+// SHA-256 over `body_utf8`, truncated to the leading 8 bytes and
+// rendered as 16 lowercase hex chars. 64 bits of digest gives a
+// 1-in-2^64 collision probability across one connection's lifetime
+// and the 16-char ETag stays under the IETF-recommended header
+// budget. RFC 7232 §2.3 requires quotes around the header value;
+// the caller wraps when assembling `ETag: "<hex>"`. Bare hex is
+// returned so the same value feeds straight into IfNoneMatchHits.
+std::string Etag(const std::string &body_utf8);
+
+
+// RFC 7232 §3.2 conditional-GET match. `if_none_match` is the raw
+// header value; `etag` is the bare-hex value returned by Etag().
+// Returns true when the caller should swap a 200 + body response
+// for a 304 Not Modified.
+//
+// Accepted client shapes (per RFC 7232 §2.3 + §3.2):
+//  * `"<hex>"`        — strong validator, RFC-canonical form
+//  * `W/"<hex>"`      — weak validator (same opaque payload)
+//  * `<hex>`          — bare hex, tolerated for non-canonical clients
+//  * `*`              — wildcard, matches any existing representation
+//  * `"<a>", W/"<b>"` — comma-separated list, any-match wins
+//
+// Whitespace around list entries is stripped; match is case-
+// sensitive on the hex payload (RFC §2.3.2 — opaque-string
+// equality).
+bool IfNoneMatchHits(const std::string &if_none_match,
+                     const std::string &etag);
+
+
+}  // namespace webcommon
+
+#endif // LIBWEBCOMMON_ETAG_H
diff --git a/src/libwebcommon/HeaderParse.cpp b/src/libwebcommon/HeaderParse.cpp
new file mode 100644
index 0000000000..de11c14fb6
--- /dev/null
+++ b/src/libwebcommon/HeaderParse.cpp
@@ -0,0 +1,122 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#include "HeaderParse.h"
+
+#include <cstring>
+
+
+// strncasecmp on POSIX is declared in <strings.h>, but most libc
+// implementations also expose it via <string.h> + <cstring>. Be
+// explicit so the build doesn't depend on the implicit include.
+#ifdef _WIN32
+#  include <string.h>
+#  define strncasecmp _strnicmp
+#else
+#  include <strings.h>
+#endif
+
+
+namespace webcommon {
+
+
+std::pair<const char*, std::size_t> FindHttpHeaderValue(
+	const char *block, const char *name)
+{
+	if (!block || !name) return {nullptr, 0};
+	const std::size_t name_len = std::strlen(name);
+	const char *line = block;
+	// `block` starts with the HTTP-version line of the request
+	// ("HTTP/1.1\r\n..."), so the first iteration walks past it to
+	// land on the first header.
+	while (*line) {
+		const char *eol = std::strstr(line, "\r\n");
+		if (!eol) break;
+		// End-of-headers marker: blank line.
+		if (eol == line) break;
+		// Move to the line *after* the current one for the next
+		// iteration before doing the match, so an early `continue`
+		// can't loop forever.
+		const char *next = eol + 2;
+		// Skip the version line on the first iteration: it doesn't
+		// start with `name:` so the strncasecmp+colon check below
+		// naturally rejects it.
+		if (line + name_len < eol
+		    && strncasecmp(line, name, name_len) == 0
+		    && line[name_len] == ':') {
+			const char *value = line + name_len + 1;
+			// Strip leading OWS per RFC 7230 §3.2.
+			while (*value == ' ' || *value == '\t') ++value;
+			// Strip trailing OWS likewise. Both sides may be
+			// present per the spec, though no real client we've
+			// ever seen sends trailing whitespace.
+			const char *value_end = eol;
+			while (value_end > value
+			       && (value_end[-1] == ' ' || value_end[-1] == '\t')) {
+				--value_end;
+			}
+			return {value, static_cast<std::size_t>(value_end - value)};
+		}
+		line = next;
+	}
+	return {nullptr, 0};
+}
+
+
+std::pair<const char*, std::size_t> FindCookieValue(
+	const char *cookies, std::size_t cookies_len, const char *cookie_name)
+{
+	if (!cookies || !cookie_name) return {nullptr, 0};
+	const std::size_t name_len = std::strlen(cookie_name);
+	const char *end = cookies + cookies_len;
+	const char *p = cookies;
+	while (p < end) {
+		// Skip leading OWS / separators.
+		while (p < end && (*p == ' ' || *p == '\t' || *p == ';')) ++p;
+		if (p + name_len + 1 > end) break;
+		if (strncasecmp(p, cookie_name, name_len) == 0
+		    && p[name_len] == '=') {
+			const char *value = p + name_len + 1;
+			const char *value_end = value;
+			while (value_end < end && *value_end != ';') ++value_end;
+			// RFC 6265 §5.2 permits OWS (SP / HTAB) on either side
+			// of `=` and between the value and the trailing `;`.
+			// Strip both ends so a header like `Cookie: foo= bar `
+			// matches a token-equal of `bar` rather than ` bar `.
+			while (value < value_end
+			    && (*value == ' ' || *value == '\t')) ++value;
+			while (value_end > value
+			    && (value_end[-1] == ' ' || value_end[-1] == '\t')) {
+				--value_end;
+			}
+			return {value, static_cast<std::size_t>(value_end - value)};
+		}
+		// Skip this cookie pair (up to next ';').
+		while (p < end && *p != ';') ++p;
+	}
+	return {nullptr, 0};
+}
+
+
+}  // namespace webcommon
diff --git a/src/libwebcommon/HeaderParse.h b/src/libwebcommon/HeaderParse.h
new file mode 100644
index 0000000000..bb0c326b13
--- /dev/null
+++ b/src/libwebcommon/HeaderParse.h
@@ -0,0 +1,64 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#ifndef LIBWEBCOMMON_HEADERPARSE_H
+#define LIBWEBCOMMON_HEADERPARSE_H
+
+#include <cstddef>
+#include <utility>
+
+
+// Line-anchored HTTP header + Cookie helpers. Pure pointer-arithmetic
+// over a CRLF-terminated header block — no copies, no allocations,
+// no dependency on the HTTP server. Line-boundary anchoring (defeats
+// `X-Foo:`-in-value header-injection) and the OWS trimming rules
+// sit in one place.
+
+namespace webcommon {
+
+
+// Walk an HTTP header block looking for `name:` at the start of a
+// line (case-insensitive). Returns a non-owning view of the value,
+// past the colon and any leading OWS, up to but not including the
+// line's CRLF; returns {nullptr, 0} on miss. `block` is expected to
+// start at the HTTP-version line (e.g. "GET / HTTP/1.1\r\n"); that
+// line is skipped on the first iteration. Line-boundary anchoring
+// defeats header-injection via a value that happens to contain a
+// literal "X-Header:" — a strstr-based scan would have matched
+// anywhere.
+std::pair<const char*, std::size_t> FindHttpHeaderValue(
+	const char *block, const char *name);
+
+
+// Extract `cookie_name=value` from a Cookie-header value (already found
+// via FindHttpHeaderValue — pass the view it returned). Returns
+// {nullptr, 0} on miss. The returned view spans from past the `=` up
+// to the next `;` or `cookies_len`, whichever comes first.
+std::pair<const char*, std::size_t> FindCookieValue(
+	const char *cookies, std::size_t cookies_len, const char *cookie_name);
+
+
+}  // namespace webcommon
+
+#endif // LIBWEBCOMMON_HEADERPARSE_H
diff --git a/src/libwebcommon/JsonWriter.cpp b/src/libwebcommon/JsonWriter.cpp
new file mode 100644
index 0000000000..0c89f7e122
--- /dev/null
+++ b/src/libwebcommon/JsonWriter.cpp
@@ -0,0 +1,227 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#include "JsonWriter.h"
+
+#include <cmath>
+#include <cstdio>
+
+
+CJsonWriter::CJsonWriter()
+	: m_buf(&m_internal),
+	  m_needs_comma(false)
+{
+}
+
+CJsonWriter::CJsonWriter(wxString *external_buf)
+	: m_buf(external_buf),
+	  m_needs_comma(false)
+{
+}
+
+void CJsonWriter::MaybeComma()
+{
+	if (m_needs_comma) {
+		*m_buf += wxT(",");
+	}
+}
+
+void CJsonWriter::BeginObject()
+{
+	MaybeComma();
+	*m_buf += wxT("{");
+	m_needs_comma = false;
+}
+
+void CJsonWriter::EndObject()
+{
+	*m_buf += wxT("}");
+	m_needs_comma = true;
+}
+
+void CJsonWriter::BeginArray()
+{
+	MaybeComma();
+	*m_buf += wxT("[");
+	m_needs_comma = false;
+}
+
+void CJsonWriter::EndArray()
+{
+	*m_buf += wxT("]");
+	m_needs_comma = true;
+}
+
+void CJsonWriter::Key(const char *name)
+{
+	Key(wxString::FromUTF8(name));
+}
+
+void CJsonWriter::Key(const wxString &name)
+{
+	MaybeComma();
+	WriteEscapedString(name);
+	*m_buf += wxT(":");
+	m_needs_comma = false;
+}
+
+void CJsonWriter::ValueNull()
+{
+	MaybeComma();
+	*m_buf += wxT("null");
+	m_needs_comma = true;
+}
+
+void CJsonWriter::ValueBool(bool v)
+{
+	MaybeComma();
+	*m_buf += v ? wxT("true") : wxT("false");
+	m_needs_comma = true;
+}
+
+void CJsonWriter::ValueInt(int64_t v)
+{
+	MaybeComma();
+	char buf[32];
+	std::snprintf(buf, sizeof(buf), "%lld", static_cast<long long>(v));
+	*m_buf += wxString::FromAscii(buf);
+	m_needs_comma = true;
+}
+
+void CJsonWriter::ValueUInt(uint64_t v)
+{
+	MaybeComma();
+	char buf[32];
+	std::snprintf(buf, sizeof(buf), "%llu", static_cast<unsigned long long>(v));
+	*m_buf += wxString::FromAscii(buf);
+	m_needs_comma = true;
+}
+
+void CJsonWriter::ValueDouble(double v)
+{
+	MaybeComma();
+	if (std::isnan(v) || std::isinf(v)) {
+		*m_buf += wxT("null");
+	} else {
+		// %.17g is the shortest round-trippable form for IEEE 754
+		// doubles. JSON doesn't allow `+Inf`, `-Inf` or `NaN` so we
+		// already handled those above.
+		char buf[64];
+		std::snprintf(buf, sizeof(buf), "%.17g", v);
+		*m_buf += wxString::FromAscii(buf);
+	}
+	m_needs_comma = true;
+}
+
+void CJsonWriter::ValueString(const wxString &s)
+{
+	MaybeComma();
+	WriteEscapedString(s);
+	m_needs_comma = true;
+}
+
+void CJsonWriter::ValueString(const char *s)
+{
+	ValueString(s ? wxString::FromUTF8(s) : wxString());
+}
+
+void CJsonWriter::ValueRaw(const wxString &json_fragment)
+{
+	MaybeComma();
+	*m_buf += json_fragment;
+	m_needs_comma = true;
+}
+
+void CJsonWriter::WriteEscapedString(const wxString &s)
+{
+	*m_buf += wxT("\"");
+	for (wxString::const_iterator i = s.begin(); i != s.end(); ++i) {
+		wxUniChar uc = *i;
+		uint32_t cp = uc.GetValue();
+		// wxString on Windows uses UTF-16 internally so supplementary-
+		// plane code points (U+10000+) come through as two surrogate
+		// halves; Linux + macOS use UTF-32 and yield the combined
+		// code point in one step. Combine the halves here so both
+		// backends emit identical `\uXXXX\uXXXX` escapes.
+		if (cp >= 0xD800 && cp <= 0xDBFF) {
+			wxString::const_iterator j = i;
+			++j;
+			bool paired = false;
+			if (j != s.end()) {
+				const uint32_t lo = wxUniChar(*j).GetValue();
+				if (lo >= 0xDC00 && lo <= 0xDFFF) {
+					cp = 0x10000u
+					   + ((cp - 0xD800u) << 10)
+					   + (lo - 0xDC00u);
+					i = j;
+					paired = true;
+				}
+			}
+			if (!paired) {
+				// Unpaired high surrogate. Falling through would
+				// emit invalid UTF-8 (CESU-8) once the buffer is
+				// utf8_str()-flushed. Replace with U+FFFD so the
+				// JSON output stays valid Unicode. Same treatment
+				// for an unpaired low surrogate below.
+				cp = 0xFFFD;
+			}
+		} else if (cp >= 0xDC00 && cp <= 0xDFFF) {
+			cp = 0xFFFD;
+		}
+		switch (cp) {
+		case '"':  *m_buf += wxT("\\\""); continue;
+		case '\\': *m_buf += wxT("\\\\"); continue;
+		case '\b': *m_buf += wxT("\\b"); continue;
+		case '\f': *m_buf += wxT("\\f"); continue;
+		case '\n': *m_buf += wxT("\\n"); continue;
+		case '\r': *m_buf += wxT("\\r"); continue;
+		case '\t': *m_buf += wxT("\\t"); continue;
+		default: break;
+		}
+		if (cp < 0x20 || cp == 0x7F) {
+			// Control characters: \uXXXX form.
+			char buf[8];
+			std::snprintf(buf, sizeof(buf), "\\u%04x",
+				static_cast<unsigned>(cp));
+			*m_buf += wxString::FromAscii(buf);
+		} else if (cp <= 0xFFFF) {
+			// BMP non-control: emit verbatim. Non-ASCII bytes ride
+			// through as the wxString native encoding and are
+			// converted to UTF-8 by the response serializer.
+			*m_buf += uc;
+		} else {
+			// Supplementary plane: emit as UTF-16 surrogate pair.
+			// This is the only escape form JSON allows above U+FFFF.
+			uint32_t v = cp - 0x10000;
+			uint32_t hi = 0xD800 | ((v >> 10) & 0x3FF);
+			uint32_t lo = 0xDC00 | (v & 0x3FF);
+			char buf[16];
+			std::snprintf(buf, sizeof(buf), "\\u%04x\\u%04x",
+				static_cast<unsigned>(hi),
+				static_cast<unsigned>(lo));
+			*m_buf += wxString::FromAscii(buf);
+		}
+	}
+	*m_buf += wxT("\"");
+}
diff --git a/src/libwebcommon/JsonWriter.h b/src/libwebcommon/JsonWriter.h
new file mode 100644
index 0000000000..490d56b1f4
--- /dev/null
+++ b/src/libwebcommon/JsonWriter.h
@@ -0,0 +1,86 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#ifndef LIBWEBCOMMON_JSONWRITER_H
+#define LIBWEBCOMMON_JSONWRITER_H
+
+#include <wx/string.h>
+#include <cstdint>
+
+
+// Streaming JSON output. Appends to an internal or caller-owned wxString
+// buffer; the buffer holds JSON text suitable for UTF-8 emission via
+// wxString::utf8_str() at flush time.
+//
+// Usage:
+//  CJsonWriter w;
+//  w.BeginObject();
+//    w.Key("name"); w.ValueString("aMule");
+//    w.Key("version"); w.ValueString("2.3.3");
+//  w.EndObject();
+//  const wxString &out = w.GetBuffer();
+//
+// Commas between siblings are inserted automatically. Calling Key()
+// outside an object, or omitting it inside one, is a programmer error
+// (no runtime check; tests cover the legal patterns).
+class CJsonWriter {
+public:
+	CJsonWriter();
+	explicit CJsonWriter(wxString *external_buf);
+
+	void BeginObject();
+	void EndObject();
+	void BeginArray();
+	void EndArray();
+
+	void Key(const char *name);
+	void Key(const wxString &name);
+
+	void ValueNull();
+	void ValueBool(bool v);
+	void ValueInt(int64_t v);
+	void ValueUInt(uint64_t v);
+	// NaN / +Inf / -Inf are emitted as `null` per JSON.
+	void ValueDouble(double v);
+	void ValueString(const wxString &s);
+	void ValueString(const char *s);
+	// Pre-formatted JSON fragment, written verbatim. Caller responsible
+	// for valid syntax. Useful when the writer is composing a response
+	// from a sub-component that already produced JSON text.
+	void ValueRaw(const wxString &json_fragment);
+
+	const wxString &GetBuffer() const { return *m_buf; }
+
+private:
+	wxString  m_internal;
+	wxString *m_buf;
+	// True when the next value/key/closer must be preceded by a comma.
+	// Reset by BeginObject/BeginArray/Key.
+	bool      m_needs_comma;
+
+	void MaybeComma();
+	void WriteEscapedString(const wxString &s);
+};
+
+#endif // LIBWEBCOMMON_JSONWRITER_H
diff --git a/src/libwebcommon/Jwt.cpp b/src/libwebcommon/Jwt.cpp
new file mode 100644
index 0000000000..69f2645c3d
--- /dev/null
+++ b/src/libwebcommon/Jwt.cpp
@@ -0,0 +1,359 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#include "Jwt.h"
+
+#include "ConstantTime.h"
+
+#define PICOJSON_USE_INT64
+#include "picojson.h"
+
+#include <cryptopp/hmac.h>
+#include <cryptopp/osrng.h>
+#include <cryptopp/sha.h>
+
+#include <cstdio>
+#include <cstdint>
+#include <stdexcept>
+#include <utility>
+
+
+namespace {
+
+const char kB64UrlChars[] =
+	"ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+	"abcdefghijklmnopqrstuvwxyz"
+	"0123456789-_";
+
+
+std::string Base64UrlEncode(const unsigned char *data, size_t len)
+{
+	std::string out;
+	out.reserve(((len + 2) / 3) * 4);
+	for (size_t i = 0; i < len; i += 3) {
+		uint32_t triple = static_cast<uint32_t>(data[i]) << 16;
+		size_t avail = 1;
+		if (i + 1 < len) { triple |= static_cast<uint32_t>(data[i + 1]) << 8; avail = 2; }
+		if (i + 2 < len) { triple |= static_cast<uint32_t>(data[i + 2]);      avail = 3; }
+		out.push_back(kB64UrlChars[(triple >> 18) & 0x3F]);
+		out.push_back(kB64UrlChars[(triple >> 12) & 0x3F]);
+		if (avail >= 2) out.push_back(kB64UrlChars[(triple >> 6) & 0x3F]);
+		if (avail >= 3) out.push_back(kB64UrlChars[ triple       & 0x3F]);
+	}
+	return out;
+}
+
+
+bool Base64UrlDecodeChar(char c, unsigned int &out)
+{
+	if (c >= 'A' && c <= 'Z') { out = static_cast<unsigned>(c - 'A');      return true; }
+	if (c >= 'a' && c <= 'z') { out = static_cast<unsigned>(c - 'a' + 26); return true; }
+	if (c >= '0' && c <= '9') { out = static_cast<unsigned>(c - '0' + 52); return true; }
+	if (c == '-')             { out = 62; return true; }
+	if (c == '_')             { out = 63; return true; }
+	return false;
+}
+
+
+bool Base64UrlDecode(const std::string &in, std::vector<unsigned char> &out)
+{
+	out.clear();
+	out.reserve(in.size() * 3 / 4 + 3);
+	uint32_t acc = 0;
+	int bits = 0;
+	for (size_t i = 0; i < in.size(); ++i) {
+		unsigned int v;
+		if (!Base64UrlDecodeChar(in[i], v)) return false;
+		acc = (acc << 6) | v;
+		bits += 6;
+		if (bits >= 8) {
+			bits -= 8;
+			out.push_back(static_cast<unsigned char>((acc >> bits) & 0xFF));
+		}
+	}
+	// A well-formed base64url string of length len(input)%4 == 0/2/3
+	// has 0/4/2 trailing bits respectively, all expected to be zero.
+	// Reject inputs that left non-zero residue — they're malformed even
+	// if every char is in the b64url alphabet.
+	if (bits > 0 && (acc & ((1u << bits) - 1)) != 0) return false;
+	// Length-mod-4 of 1 is impossible for a valid base64url encoding.
+	if ((in.size() & 3) == 1) return false;
+	return true;
+}
+
+
+// HMAC-SHA-256(secret, signing_input) → 32-byte MAC. CryptoPP's HMAC
+// handles keys of any length per RFC 2104.
+void HmacSha256(const CryptoPP::SecByteBlock     &secret,
+                const std::string                &signing_input,
+                unsigned char out_mac[CryptoPP::SHA256::DIGESTSIZE])
+{
+	CryptoPP::HMAC<CryptoPP::SHA256> hmac(
+		secret.empty() ? nullptr : secret.data(), secret.size());
+	hmac.Update(
+		reinterpret_cast<const unsigned char *>(signing_input.data()),
+		signing_input.size());
+	hmac.Final(out_mac);
+}
+
+
+// 24 h JWT expiry. Documented in the v0 API spec.
+const std::time_t TOKEN_LIFETIME_SECONDS = 24 * 60 * 60;
+
+// 128-bit `jti`. Wide enough that collisions are infeasible across the
+// revocation-list lifetime, narrow enough that 22 b64url chars fit
+// comfortably in cookie/header payloads.
+const size_t JTI_BYTES = 16;
+
+// Hard cap on JSON nesting in a JWT header or payload.
+//
+// picojson's _parse_array / _parse_object is unbounded recursive
+// descent and both parse sites in Verify() run BEFORE the MAC
+// compare returns its verdict — an unauthenticated peer can blow
+// the worker stack with `{"a":{"a":...}}` nested deep enough.
+// musl's 128 KiB pthread stack limits the attack to ~300-600
+// frames; glibc is higher but still finite.
+//
+// Real JWT payloads here are flat (scalar claims: role / exp /
+// iat / jti / typ / alg) so 8 would suffice. 32 leaves headroom
+// for a third-party producer accepted later.
+//
+// The check sums `{` + `[` in the decoded JSON. Openers inside
+// string literals are counted too — false positives — but our
+// payloads don't legitimately contain unbalanced braces in
+// strings, so the conservative direction is fine.
+const std::size_t MAX_JSON_OPENERS = 32;
+
+bool DepthWithinLimit(const std::string &json)
+{
+	std::size_t count = 0;
+	for (char c : json) {
+		if (c == '{' || c == '[') {
+			if (++count > MAX_JSON_OPENERS) return false;
+		}
+	}
+	return true;
+}
+
+} // namespace
+
+
+CJwt::CJwt(std::vector<unsigned char> secret)
+	: m_secret(secret.empty() ? nullptr : secret.data(), secret.size())
+{
+	// An empty signing key is always a config bug (truncated
+	// amuleapi-jwt-secret read, missing file write, etc.). Refusing
+	// it at construction is the cheapest way to avoid the failure
+	// mode where the daemon happily issues and verifies tokens
+	// signed with a zero-length key. CryptoPP's HMAC accepts a null
+	// key + len=0 without complaint, which is why this slipped
+	// through MAC checking.
+	if (m_secret.empty()) {
+		throw std::invalid_argument(
+			"CJwt: signing secret must not be empty");
+	}
+	// Wipe the caller's copy now that we've taken our own. The
+	// SecByteBlock owns the live copy and will scrub itself on
+	// destruction; the std::vector the caller passed in is
+	// moved-from, leaving any residual bytes outside our control.
+	// Best-effort: explicitly overwrite if any bytes remain.
+	if (!secret.empty()) {
+		std::fill(secret.begin(), secret.end(), 0);
+	}
+}
+
+
+CJwt::IssuedToken CJwt::Issue(Role role)
+{
+	IssuedToken out;
+	const std::time_t now = std::time(nullptr);
+	out.expires_at = now + TOKEN_LIFETIME_SECONDS;
+
+	unsigned char jti_bytes[JTI_BYTES];
+	CryptoPP::AutoSeededRandomPool rng;
+	rng.GenerateBlock(jti_bytes, sizeof(jti_bytes));
+	out.jti = Base64UrlEncode(jti_bytes, sizeof(jti_bytes));
+
+	const char *role_str = (role == Role::ADMIN) ? "admin" : "guest";
+
+	const std::string header_json = "{\"alg\":\"HS256\",\"typ\":\"JWT\"}";
+
+	char payload_buf[256];
+	std::snprintf(payload_buf, sizeof(payload_buf),
+		"{\"role\":\"%s\",\"iat\":%lld,\"exp\":%lld,\"jti\":\"%s\"}",
+		role_str,
+		static_cast<long long>(now),
+		static_cast<long long>(out.expires_at),
+		out.jti.c_str());
+	const std::string payload_json = payload_buf;
+
+	const std::string header_b64 = Base64UrlEncode(
+		reinterpret_cast<const unsigned char *>(header_json.data()),
+		header_json.size());
+	const std::string payload_b64 = Base64UrlEncode(
+		reinterpret_cast<const unsigned char *>(payload_json.data()),
+		payload_json.size());
+	const std::string signing_input = header_b64 + "." + payload_b64;
+
+	unsigned char mac[CryptoPP::SHA256::DIGESTSIZE];
+	HmacSha256(m_secret, signing_input, mac);
+	const std::string sig_b64 = Base64UrlEncode(mac, sizeof(mac));
+
+	out.token = signing_input + "." + sig_b64;
+	return out;
+}
+
+
+bool CJwt::Verify(const std::string &token, VerifyResult &out) const
+{
+	// Reject before any Base64UrlDecode walk on absurd-length tokens.
+	// A legitimate amuleapi token is ~280 bytes (header 36 + payload
+	// ~120 + signature 43, each base64url-encoded); 4 KiB leaves
+	// ~10x headroom. Without this cap an unauthenticated peer can
+	// burn three full-token walks per request before the MAC
+	// compare rejects, which is a cheap CPU-amplification surface
+	// against the listener (1 MiB body cap × N concurrent peers).
+	if (token.size() > 4096) return false;
+	// Two dots split the token into three sections.
+	const size_t first_dot = token.find('.');
+	if (first_dot == std::string::npos) return false;
+	const size_t second_dot = token.find('.', first_dot + 1);
+	if (second_dot == std::string::npos) return false;
+	if (token.find('.', second_dot + 1) != std::string::npos) return false;
+
+	const std::string header_b64  = token.substr(0, first_dot);
+	const std::string payload_b64 = token.substr(first_dot + 1,
+	                                              second_dot - first_dot - 1);
+	const std::string sig_b64     = token.substr(second_dot + 1);
+	const std::string signing_input = header_b64 + "." + payload_b64;
+
+	// Recompute MAC and compare in constant time before validating the
+	// header, so timing of a malformed header is indistinguishable from
+	// a wrong MAC. Not exploitable today (32-byte secret makes collision
+	// infeasible) but keeps the channel closed against future shifts.
+	unsigned char mac[CryptoPP::SHA256::DIGESTSIZE];
+	HmacSha256(m_secret, signing_input, mac);
+	const std::string expected_sig = Base64UrlEncode(mac, sizeof(mac));
+	if (!webcommon::ConstantTimeEquals(expected_sig, sig_b64)) {
+		return false;
+	}
+
+	// Defence in depth: validate the header announces HS256.
+	// The MAC already matches our secret so only we could have signed
+	// the token; this closes the door against future key-confusion if
+	// asymmetric algorithms are ever added.
+	{
+		std::vector<unsigned char> header_bytes;
+		if (!Base64UrlDecode(header_b64, header_bytes)) return false;
+		const std::string header_json(
+			header_bytes.begin(), header_bytes.end());
+		if (!DepthWithinLimit(header_json)) return false;
+		picojson::value hv;
+		std::string herr;
+		picojson::parse(hv, header_json.begin(), header_json.end(), &herr);
+		if (!herr.empty() || !hv.is<picojson::object>()) return false;
+		const picojson::object &hobj = hv.get<picojson::object>();
+		const auto alg_it = hobj.find("alg");
+		if (alg_it == hobj.end()
+		    || !alg_it->second.is<std::string>()
+		    || alg_it->second.get<std::string>() != "HS256") {
+			return false;
+		}
+		// `typ` is optional in RFC 7519, but if present it must say JWT.
+		const auto typ_it = hobj.find("typ");
+		if (typ_it != hobj.end()
+		    && (!typ_it->second.is<std::string>()
+		        || typ_it->second.get<std::string>() != "JWT")) {
+			return false;
+		}
+	}
+
+	// Decode and parse the payload.
+	std::vector<unsigned char> payload_bytes;
+	if (!Base64UrlDecode(payload_b64, payload_bytes)) return false;
+	const std::string payload_json(payload_bytes.begin(), payload_bytes.end());
+	if (!DepthWithinLimit(payload_json)) return false;
+
+	picojson::value v;
+	std::string err;
+	picojson::parse(v, payload_json.begin(), payload_json.end(), &err);
+	if (!err.empty() || !v.is<picojson::object>()) return false;
+
+	const picojson::object &obj = v.get<picojson::object>();
+	const auto role_it = obj.find("role");
+	const auto exp_it  = obj.find("exp");
+	const auto jti_it  = obj.find("jti");
+	if (role_it == obj.end() || !role_it->second.is<std::string>()) return false;
+	if (exp_it  == obj.end() || !exp_it->second.is<int64_t>())      return false;
+	if (jti_it  == obj.end() || !jti_it->second.is<std::string>())  return false;
+
+	const std::string role_str = role_it->second.get<std::string>();
+	if      (role_str == "admin") out.role = Role::ADMIN;
+	else if (role_str == "guest") out.role = Role::GUEST;
+	else return false;
+
+	out.exp = static_cast<std::time_t>(exp_it->second.get<int64_t>());
+	{
+		// Five-second clock-skew tolerance on the exp check. Issuer
+		// and verifier today run in the same process so the skew is
+		// always zero; tomorrow they may not (federated tokens,
+		// reverse-proxy auth handoff, etc.) and a token landing on
+		// the verifier microseconds after exp shouldn't 401 the
+		// caller's last request. A few seconds of leeway is the
+		// standard RFC 7519 §4.1.4 implementation note.
+		constexpr std::time_t skew = 5;
+		const std::time_t now = std::time(nullptr);
+		if (out.exp + skew <= now) return false;   // expired
+
+		// `iat` (issued-at, §4.1.6) is mandatory. Without an iat
+		// claim a token has unbounded lifetime — an attacker who
+		// somehow gained mint capability (compromised secret,
+		// stolen --jwt-secret file, …) could otherwise issue a
+		// token with exp = year-2100 and bypass the lifetime cap
+		// entirely. With iat mandatory we additionally cap
+		// (exp - iat) ≤ TOKEN_LIFETIME_SECONDS + skew so the
+		// cap survives a future Issue() change too.
+		const auto iat_it = obj.find("iat");
+		if (iat_it == obj.end() || !iat_it->second.is<int64_t>()) {
+			return false;
+		}
+		const std::time_t iat = static_cast<std::time_t>(
+			iat_it->second.get<int64_t>());
+		if (iat > now + 60) return false;          // iat in the future
+		if (out.exp <= iat) return false;          // exp must follow iat
+		if (out.exp - iat > TOKEN_LIFETIME_SECONDS + skew) {
+			return false;                          // lifetime cap
+		}
+	}
+
+	out.jti = jti_it->second.get<std::string>();
+	if (out.jti.empty()) return false;
+
+	// nbf (RFC 7519 §4.1.5, "not before") is intentionally not
+	// enforced: Issue() never emits the claim and we don't accept
+	// externally-issued tokens. If federated tokens are ever added,
+	// the check belongs immediately above the `exp` check.
+
+	return true;
+}
diff --git a/src/libwebcommon/Jwt.h b/src/libwebcommon/Jwt.h
new file mode 100644
index 0000000000..45f26bc470
--- /dev/null
+++ b/src/libwebcommon/Jwt.h
@@ -0,0 +1,97 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#ifndef LIBWEBCOMMON_JWT_H
+#define LIBWEBCOMMON_JWT_H
+
+#include <ctime>
+#include <string>
+#include <vector>
+
+#include <cryptopp/secblock.h>
+
+#include "Role.h"
+
+
+// HS256 JWT machinery for the /api/v0 surface. Token shape per
+// RFC 7519: <base64url(header)>.<base64url(payload)>.<base64url(sig)>
+//
+//   header  = {"alg":"HS256","typ":"JWT"}
+//   payload = {"role":"admin"|"guest","iat":<unix>,"exp":<unix>,
+//              "jti":"<random base64url>"}
+//   sig     = HMAC-SHA-256(secret, header_b64 + "." + payload_b64)
+//
+// The HMAC secret is supplied at construction by the owning binary
+// (amuleapi loads it from `${config_dir}/amuleapi-jwt-secret`); this
+// class never touches the filesystem.
+//
+// `jti` (RFC 7519 §4.1.7) is a 128-bit random identifier emitted
+// per Issue() and surfaced through Verify() so the owning binary
+// can run a server-side revocation list — `/auth/logout` adds the
+// jti, Verify rejects on the next request. The revocation set lives
+// in the owner, not in this library.
+class CJwt {
+public:
+	// `secret` is the HMAC-SHA-256 key. amuleapi loads 32 random bytes
+	// (256 bits, matching the digest size) from amuleapi-jwt-secret;
+	// the test-only constructor passes a deterministic fill so test
+	// vectors are reproducible.
+	explicit CJwt(std::vector<unsigned char> secret);
+
+	struct IssuedToken {
+		std::string token;
+		std::string jti;          // emitted in the `jti` claim
+		std::time_t expires_at;   // matches the `exp` claim
+	};
+
+	// Generates a fresh JWT for the given role with a 24 h expiry.
+	// Each call returns a fresh `jti`.
+	IssuedToken Issue(Role role);
+
+	struct VerifyResult {
+		Role        role;
+		std::time_t exp;
+		std::string jti;          // for revocation-list lookup
+	};
+
+	// Verifies a token's signature, header `alg`/`typ`, and payload
+	// shape. Returns true and fills `out` on success; false on bad
+	// signature, expired `exp`, malformed base64, malformed JSON, or
+	// wrong algorithm. Constant-time MAC compare runs before the
+	// header `alg` parse so the timing channel doesn't distinguish
+	// "wrong MAC" from "malformed header".
+	bool Verify(const std::string &token, VerifyResult &out) const;
+
+private:
+	// CryptoPP::SecBlock zeros its backing buffer at destruction
+	// (and on reallocation via AlignedAllocator), so a coredump or
+	// swap from a long-lived amuleapi process won't leak the HMAC
+	// signing key the same way a plain std::vector<unsigned char>
+	// would. The constructor accepts a vector for caller convenience
+	// (config-load doesn't want to drag SecBlock into its surface)
+	// and copies into the SecBlock once.
+	CryptoPP::SecByteBlock m_secret;
+};
+
+#endif // LIBWEBCOMMON_JWT_H
diff --git a/src/libwebcommon/PathPatterns.cpp b/src/libwebcommon/PathPatterns.cpp
new file mode 100644
index 0000000000..c04f5a508b
--- /dev/null
+++ b/src/libwebcommon/PathPatterns.cpp
@@ -0,0 +1,219 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#include "PathPatterns.h"
+
+
+namespace web_api_path {
+
+
+std::vector<std::string> SplitPath(const std::string &path)
+{
+	std::vector<std::string> out;
+	if (path.empty()) {
+		return out;
+	}
+	// A leading '/' is the conventional "absolute" form. We skip the
+	// empty segment it would otherwise produce; a trailing '/' still
+	// emits its empty segment so it's distinguishable from "no
+	// trailing slash".
+	size_t i = (path[0] == '/') ? 1 : 0;
+	std::string cur;
+	for (; i < path.size(); ++i) {
+		if (path[i] == '/') {
+			out.push_back(cur);
+			cur.clear();
+		} else {
+			cur += path[i];
+		}
+	}
+	out.push_back(cur);
+	return out;
+}
+
+
+bool LooksMalicious(const std::string &path)
+{
+	// NUL byte anywhere. Some downstream tooling (sscanf, fopen) is
+	// NUL-terminated; embedded NULs are a classic injection vector.
+	if (path.find('\0') != std::string::npos) return true;
+
+	// Encoded NUL — explicit reject even though today's routes don't
+	// percent-decode path segments. A future hash-by-name endpoint
+	// that does decode would otherwise admit this.
+	for (size_t i = 0; i + 2 < path.size(); ++i) {
+		if (path[i] != '%') continue;
+		const char h = path[i + 1];
+		const char l = path[i + 2];
+		if (h == '0' && l == '0') return true;
+	}
+
+	// Encoded ".." (percent-encoded dot). Match `%2e` and `%2E` in
+	// both upper/lower hex forms. We don't bother with the more
+	// exotic `%2e%2E`/`%2E%2e` orderings — the simple loop catches
+	// any pair of "is a `%2e`-looking triplet" tokens that are
+	// adjacent.
+	for (size_t i = 0; i + 5 < path.size(); ++i) {
+		const bool dot1 = path[i] == '%'
+		    && path[i + 1] == '2'
+		    && (path[i + 2] == 'e' || path[i + 2] == 'E');
+		if (!dot1) continue;
+		const bool dot2 = path[i + 3] == '%'
+		    && path[i + 4] == '2'
+		    && (path[i + 5] == 'e' || path[i + 5] == 'E');
+		if (dot2) return true;
+	}
+
+	// Literal ".." segment. SplitPath would happily emit a "..":
+	// segment-walk every "/"-delimited chunk and reject if it
+	// equals "..".
+	size_t seg_start = (path[0] == '/') ? 1 : 0;
+	for (size_t i = seg_start; i <= path.size(); ++i) {
+		const bool boundary = (i == path.size()) || (path[i] == '/');
+		if (!boundary) continue;
+		if (i - seg_start == 2
+		    && path[seg_start] == '.'
+		    && path[seg_start + 1] == '.') {
+			return true;
+		}
+		seg_start = i + 1;
+	}
+
+	return false;
+}
+
+
+namespace {
+int HexNibble(char c)
+{
+	if (c >= '0' && c <= '9') return c - '0';
+	if (c >= 'a' && c <= 'f') return c - 'a' + 10;
+	if (c >= 'A' && c <= 'F') return c - 'A' + 10;
+	return -1;
+}
+
+// Percent-decode an application/x-www-form-urlencoded fragment.
+// `+` → space (form convention); `%hh` → byte; malformed `%hh`
+// passes through verbatim so a stray `%` doesn't drop characters.
+std::string PercentDecode(const std::string &in)
+{
+	std::string out;
+	out.reserve(in.size());
+	for (size_t i = 0; i < in.size(); ++i) {
+		if (in[i] == '+') { out += ' '; }
+		else if (in[i] == '%' && i + 2 < in.size()) {
+			const int hi = HexNibble(in[i + 1]);
+			const int lo = HexNibble(in[i + 2]);
+			if (hi >= 0 && lo >= 0) {
+				out += static_cast<char>((hi << 4) | lo);
+				i += 2;
+			} else {
+				out += in[i];
+			}
+		} else {
+			out += in[i];
+		}
+	}
+	return out;
+}
+}  // namespace
+
+std::map<std::string, std::string> ParseQuery(const std::string &q)
+{
+	std::map<std::string, std::string> out;
+	std::string key, val;
+	bool in_val = false;
+	for (size_t i = 0; i < q.size(); ++i) {
+		const char c = q[i];
+		if (c == '=' && !in_val) {
+			in_val = true;
+		} else if (c == '&') {
+			if (!key.empty()) {
+				out[PercentDecode(key)] = PercentDecode(val);
+			}
+			key.clear();
+			val.clear();
+			in_val = false;
+		} else {
+			(in_val ? val : key) += c;
+		}
+	}
+	if (!key.empty()) {
+		out[PercentDecode(key)] = PercentDecode(val);
+	}
+	return out;
+}
+
+
+RoutePattern ParsePattern(const std::string &pattern)
+{
+	RoutePattern out;
+	out.segments = SplitPath(pattern);
+	out.capture_names.reserve(out.segments.size());
+	for (size_t i = 0; i < out.segments.size(); ++i) {
+		const std::string &seg = out.segments[i];
+		if (seg.size() >= 2 && seg.front() == '{' && seg.back() == '}') {
+			out.capture_names.push_back(seg.substr(1, seg.size() - 2));
+		} else {
+			out.capture_names.push_back(std::string());
+		}
+	}
+	return out;
+}
+
+
+bool Match(const RoutePattern &pattern,
+           const std::vector<std::string> &path_segments,
+           std::map<std::string, std::string> &out_captures)
+{
+	if (pattern.segments.size() != path_segments.size()) {
+		return false;
+	}
+	std::map<std::string, std::string> caps;
+	for (size_t i = 0; i < pattern.segments.size(); ++i) {
+		if (!pattern.capture_names[i].empty()) {
+			caps[pattern.capture_names[i]] = path_segments[i];
+		} else if (pattern.segments[i] != path_segments[i]) {
+			return false;
+		}
+	}
+	out_captures.swap(caps);
+	return true;
+}
+
+
+bool ShapeEqual(const RoutePattern &a, const RoutePattern &b)
+{
+	if (a.segments.size() != b.segments.size()) return false;
+	for (size_t i = 0; i < a.segments.size(); ++i) {
+		const bool a_cap = !a.capture_names[i].empty();
+		const bool b_cap = !b.capture_names[i].empty();
+		if (a_cap != b_cap) return false;
+		if (!a_cap && a.segments[i] != b.segments[i]) return false;
+	}
+	return true;
+}
+
+
+} // namespace web_api_path
diff --git a/src/libwebcommon/PathPatterns.h b/src/libwebcommon/PathPatterns.h
new file mode 100644
index 0000000000..f7f5c50109
--- /dev/null
+++ b/src/libwebcommon/PathPatterns.h
@@ -0,0 +1,90 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#ifndef LIBWEBCOMMON_PATHPATTERNS_H
+#define LIBWEBCOMMON_PATHPATTERNS_H
+
+#include <map>
+#include <string>
+#include <vector>
+
+
+// URL-path primitives used by the REST router. Kept dependency-free
+// (no wx, no amule-internal headers) so the unit tests can link this
+// translation unit on its own.
+
+namespace web_api_path {
+
+
+// Splits `path` on '/'. A leading '/' produces no leading empty
+// segment; a trailing '/' produces a trailing empty segment (so
+// "/a/" → ["a", ""] is distinguishable from "/a" → ["a"]).
+std::vector<std::string> SplitPath(const std::string &path);
+
+
+// Returns true if the raw path looks like a traversal/injection
+// attempt: contains a NUL byte, encoded NUL (%00), a literal ".."
+// segment, or percent-encoded ".." (`%2e%2e` in any case).
+// Defence-in-depth — call before routing, reject with 400. Any
+// future endpoint that admits path captures inherits the
+// protection.
+bool LooksMalicious(const std::string &path);
+
+
+// Parses ?k=v&k2=v2 into a map. Percent-decodes `%hh` pairs and
+// converts `+` to space per application/x-www-form-urlencoded.
+// Malformed `%hh` triplets pass through verbatim so a stray `%` in
+// a path query doesn't silently drop characters.
+std::map<std::string, std::string> ParseQuery(const std::string &q);
+
+
+// A pattern is a path string with optional `{name}` capture segments.
+// Example: "/downloads/{hash}/pause" parses to
+//  segments      = ["downloads", "{hash}", "pause"]
+//  capture_names = ["", "hash", ""]
+struct RoutePattern {
+	std::vector<std::string> segments;
+	// Per-segment capture name. Empty when the segment is a literal.
+	std::vector<std::string> capture_names;
+};
+
+RoutePattern ParsePattern(const std::string &pattern);
+
+
+// Matches `path_segments` against `pattern`. On match, fills
+// `out_captures` with the captured segment values and returns true.
+bool Match(const RoutePattern &pattern,
+           const std::vector<std::string> &path_segments,
+           std::map<std::string, std::string> &out_captures);
+
+
+// Two patterns are "shape-equivalent" if they would match the same
+// set of paths regardless of capture names. Used at route-registration
+// time to flag duplicate routes.
+bool ShapeEqual(const RoutePattern &a, const RoutePattern &b);
+
+
+} // namespace web_api_path
+
+#endif // LIBWEBCOMMON_PATHPATTERNS_H
diff --git a/src/libwebcommon/Role.h b/src/libwebcommon/Role.h
new file mode 100644
index 0000000000..1a5f3d57e2
--- /dev/null
+++ b/src/libwebcommon/Role.h
@@ -0,0 +1,39 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#ifndef LIBWEBCOMMON_ROLE_H
+#define LIBWEBCOMMON_ROLE_H
+
+
+// Role enumeration shared between the REST API dispatcher and the JWT
+// machinery. Kept in its own tiny header so the rest of libwebcommon
+// (and the API handlers that consume it) can refer to roles without
+// pulling in the full Jwt header.
+enum class Role {
+	PUBLIC,   // No credentials required (login, version)
+	GUEST,    // Authenticated as any role (read-only endpoints)
+	ADMIN     // Authenticated as admin (mutating endpoints)
+};
+
+#endif // LIBWEBCOMMON_ROLE_H
diff --git a/src/libwebcommon/picojson.LICENSE b/src/libwebcommon/picojson.LICENSE
new file mode 100644
index 0000000000..cc04ed4c8e
--- /dev/null
+++ b/src/libwebcommon/picojson.LICENSE
@@ -0,0 +1,33 @@
+Copyright 2009-2010 Cybozu Labs, Inc.
+Copyright 2011-2014 Kazuho Oku
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.
+
+---
+
+Upstream: https://github.com/kazuho/picojson (1.3.0)
+Vendored at src/libwebcommon/picojson.h. The file is unmodified upstream
+1.3.0; PICOJSON_USE_INT64 is defined locally in src/libwebcommon/Jwt.cpp
+before #include "picojson.h" rather than as a modification to the
+upstream header.
diff --git a/src/libwebcommon/picojson.h b/src/libwebcommon/picojson.h
new file mode 100644
index 0000000000..48bb64e672
--- /dev/null
+++ b/src/libwebcommon/picojson.h
@@ -0,0 +1,1010 @@
+/*
+ * Copyright 2009-2010 Cybozu Labs, Inc.
+ * Copyright 2011-2014 Kazuho Oku
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ */
+#ifndef picojson_h
+#define picojson_h
+
+#include <algorithm>
+#include <cstdio>
+#include <cstdlib>
+#include <cstring>
+#include <iostream>
+#include <iterator>
+#include <limits>
+#include <map>
+#include <stdexcept>
+#include <string>
+#include <vector>
+
+// for isnan/isinf
+#if __cplusplus>=201103L
+# include <cmath>
+#else
+extern "C" {
+# ifdef _MSC_VER
+#  include <float.h>
+# elif defined(__INTEL_COMPILER)
+#  include <mathimf.h>
+# else
+#  include <math.h>
+# endif
+}
+#endif
+
+// experimental support for int64_t (see README.mkdn for detail)
+#ifdef PICOJSON_USE_INT64
+# define __STDC_FORMAT_MACROS
+# include <errno.h>
+# include <inttypes.h>
+#endif
+
+// to disable the use of localeconv(3), set PICOJSON_USE_LOCALE to 0
+#ifndef PICOJSON_USE_LOCALE
+# define PICOJSON_USE_LOCALE 1
+#endif
+#if PICOJSON_USE_LOCALE
+extern "C" {
+# include <locale.h>
+}
+#endif
+
+#ifndef PICOJSON_ASSERT
+# define PICOJSON_ASSERT(e) do { if (! (e)) throw std::runtime_error(#e); } while (0)
+#endif
+
+#ifdef _MSC_VER
+    #define SNPRINTF _snprintf_s
+    #pragma warning(push)
+    #pragma warning(disable : 4244) // conversion from int to char
+    #pragma warning(disable : 4127) // conditional expression is constant
+    #pragma warning(disable : 4702) // unreachable code
+#else
+    #define SNPRINTF snprintf
+#endif
+
+namespace picojson {
+  
+  enum {
+    null_type,
+    boolean_type,
+    number_type,
+    string_type,
+    array_type,
+    object_type
+#ifdef PICOJSON_USE_INT64
+    , int64_type
+#endif
+  };
+  
+  enum {
+    INDENT_WIDTH = 2
+  };
+
+  struct null {};
+  
+  class value {
+  public:
+    typedef std::vector<value> array;
+    typedef std::map<std::string, value> object;
+    union _storage {
+      bool boolean_;
+      double number_;
+#ifdef PICOJSON_USE_INT64
+      int64_t int64_;
+#endif
+      std::string* string_;
+      array* array_;
+      object* object_;
+    };
+  protected:
+    int type_;
+    _storage u_;
+  public:
+    value();
+    value(int type, bool);
+    explicit value(bool b);
+#ifdef PICOJSON_USE_INT64
+    explicit value(int64_t i);
+#endif
+    explicit value(double n);
+    explicit value(const std::string& s);
+    explicit value(const array& a);
+    explicit value(const object& o);
+    explicit value(const char* s);
+    value(const char* s, size_t len);
+    ~value();
+    value(const value& x);
+    value& operator=(const value& x);
+    void swap(value& x);
+    template <typename T> bool is() const;
+    template <typename T> const T& get() const;
+    template <typename T> T& get();
+    bool evaluate_as_boolean() const;
+    const value& get(size_t idx) const;
+    const value& get(const std::string& key) const;
+    value& get(size_t idx);
+    value& get(const std::string& key);
+
+    bool contains(size_t idx) const;
+    bool contains(const std::string& key) const;
+    std::string to_str() const;
+    template <typename Iter> void serialize(Iter os, bool prettify = false) const;
+    std::string serialize(bool prettify = false) const;
+  private:
+    template <typename T> value(const T*); // intentionally defined to block implicit conversion of pointer to bool
+    template <typename Iter> static void _indent(Iter os, int indent);
+    template <typename Iter> void _serialize(Iter os, int indent) const;
+    std::string _serialize(int indent) const;
+  };
+  
+  typedef value::array array;
+  typedef value::object object;
+  
+  inline value::value() : type_(null_type) {}
+  
+  inline value::value(int type, bool) : type_(type) {
+    switch (type) {
+#define INIT(p, v) case p##type: u_.p = v; break
+      INIT(boolean_, false);
+      INIT(number_, 0.0);
+#ifdef PICOJSON_USE_INT64
+      INIT(int64_, 0);
+#endif
+      INIT(string_, new std::string());
+      INIT(array_, new array());
+      INIT(object_, new object());
+#undef INIT
+    default: break;
+    }
+  }
+  
+  inline value::value(bool b) : type_(boolean_type) {
+    u_.boolean_ = b;
+  }
+
+#ifdef PICOJSON_USE_INT64
+  inline value::value(int64_t i) : type_(int64_type) {
+    u_.int64_ = i;
+  }
+#endif
+
+  inline value::value(double n) : type_(number_type) {
+    if (
+#ifdef _MSC_VER
+        ! _finite(n)
+#elif __cplusplus>=201103L || !(defined(isnan) && defined(isinf))
+		std::isnan(n) || std::isinf(n)
+#else
+        isnan(n) || isinf(n)
+#endif
+        ) {
+      throw std::overflow_error("");
+    }
+    u_.number_ = n;
+  }
+  
+  inline value::value(const std::string& s) : type_(string_type) {
+    u_.string_ = new std::string(s);
+  }
+  
+  inline value::value(const array& a) : type_(array_type) {
+    u_.array_ = new array(a);
+  }
+  
+  inline value::value(const object& o) : type_(object_type) {
+    u_.object_ = new object(o);
+  }
+  
+  inline value::value(const char* s) : type_(string_type) {
+    u_.string_ = new std::string(s);
+  }
+  
+  inline value::value(const char* s, size_t len) : type_(string_type) {
+    u_.string_ = new std::string(s, len);
+  }
+  
+  inline value::~value() {
+    switch (type_) {
+#define DEINIT(p) case p##type: delete u_.p; break
+      DEINIT(string_);
+      DEINIT(array_);
+      DEINIT(object_);
+#undef DEINIT
+    default: break;
+    }
+  }
+  
+  inline value::value(const value& x) : type_(x.type_) {
+    switch (type_) {
+#define INIT(p, v) case p##type: u_.p = v; break
+      INIT(string_, new std::string(*x.u_.string_));
+      INIT(array_, new array(*x.u_.array_));
+      INIT(object_, new object(*x.u_.object_));
+#undef INIT
+    default:
+      u_ = x.u_;
+      break;
+    }
+  }
+  
+  inline value& value::operator=(const value& x) {
+    if (this != &x) {
+      value t(x);
+      swap(t);
+    }
+    return *this;
+  }
+  
+  inline void value::swap(value& x) {
+    std::swap(type_, x.type_);
+    std::swap(u_, x.u_);
+  }
+  
+#define IS(ctype, jtype)			     \
+  template <> inline bool value::is<ctype>() const { \
+    return type_ == jtype##_type;		     \
+  }
+  IS(null, null)
+  IS(bool, boolean)
+#ifdef PICOJSON_USE_INT64
+  IS(int64_t, int64)
+#endif
+  IS(std::string, string)
+  IS(array, array)
+  IS(object, object)
+#undef IS
+  template <> inline bool value::is<double>() const {
+    return type_ == number_type
+#ifdef PICOJSON_USE_INT64
+      || type_ == int64_type
+#endif
+      ;
+  }
+  
+#define GET(ctype, var)						\
+  template <> inline const ctype& value::get<ctype>() const {	\
+    PICOJSON_ASSERT("type mismatch! call is<type>() before get<type>()" \
+	   && is<ctype>());				        \
+    return var;							\
+  }								\
+  template <> inline ctype& value::get<ctype>() {		\
+    PICOJSON_ASSERT("type mismatch! call is<type>() before get<type>()"	\
+	   && is<ctype>());					\
+    return var;							\
+  }
+  GET(bool, u_.boolean_)
+  GET(std::string, *u_.string_)
+  GET(array, *u_.array_)
+  GET(object, *u_.object_)
+#ifdef PICOJSON_USE_INT64
+  GET(double, (type_ == int64_type && (const_cast<value*>(this)->type_ = number_type, const_cast<value*>(this)->u_.number_ = u_.int64_), u_.number_))
+  GET(int64_t, u_.int64_)
+#else
+  GET(double, u_.number_)
+#endif
+#undef GET
+  
+  inline bool value::evaluate_as_boolean() const {
+    switch (type_) {
+    case null_type:
+      return false;
+    case boolean_type:
+      return u_.boolean_;
+    case number_type:
+      return u_.number_ != 0;
+    case string_type:
+      return ! u_.string_->empty();
+    default:
+      return true;
+    }
+  }
+  
+  inline const value& value::get(size_t idx) const {
+    static value s_null;
+    PICOJSON_ASSERT(is<array>());
+    return idx < u_.array_->size() ? (*u_.array_)[idx] : s_null;
+  }
+
+  inline value& value::get(size_t idx) {
+    static value s_null;
+    PICOJSON_ASSERT(is<array>());
+    return idx < u_.array_->size() ? (*u_.array_)[idx] : s_null;
+  }
+
+  inline const value& value::get(const std::string& key) const {
+    static value s_null;
+    PICOJSON_ASSERT(is<object>());
+    object::const_iterator i = u_.object_->find(key);
+    return i != u_.object_->end() ? i->second : s_null;
+  }
+
+  inline value& value::get(const std::string& key) {
+    static value s_null;
+    PICOJSON_ASSERT(is<object>());
+    object::iterator i = u_.object_->find(key);
+    return i != u_.object_->end() ? i->second : s_null;
+  }
+
+  inline bool value::contains(size_t idx) const {
+    PICOJSON_ASSERT(is<array>());
+    return idx < u_.array_->size();
+  }
+
+  inline bool value::contains(const std::string& key) const {
+    PICOJSON_ASSERT(is<object>());
+    object::const_iterator i = u_.object_->find(key);
+    return i != u_.object_->end();
+  }
+  
+  inline std::string value::to_str() const {
+    switch (type_) {
+    case null_type:      return "null";
+    case boolean_type:   return u_.boolean_ ? "true" : "false";
+#ifdef PICOJSON_USE_INT64
+    case int64_type: {
+      char buf[sizeof("-9223372036854775808")];
+      SNPRINTF(buf, sizeof(buf), "%" PRId64, u_.int64_);
+      return buf;
+    }
+#endif
+    case number_type:    {
+      char buf[256];
+      double tmp;
+      SNPRINTF(buf, sizeof(buf), fabs(u_.number_) < (1ULL << 53) && modf(u_.number_, &tmp) == 0 ? "%.f" : "%.17g", u_.number_);
+#if PICOJSON_USE_LOCALE
+      char *decimal_point = localeconv()->decimal_point;
+      if (strcmp(decimal_point, ".") != 0) {
+        size_t decimal_point_len = strlen(decimal_point);
+        for (char *p = buf; *p != '\0'; ++p) {
+          if (strncmp(p, decimal_point, decimal_point_len) == 0) {
+            return std::string(buf, p) + "." + (p + decimal_point_len);
+          }
+        }
+      }
+#endif
+      return buf;
+    }
+    case string_type:    return *u_.string_;
+    case array_type:     return "array";
+    case object_type:    return "object";
+    default:             PICOJSON_ASSERT(0);
+#ifdef _MSC_VER
+      __assume(0);
+#endif
+    }
+    return std::string();
+  }
+  
+  template <typename Iter> void copy(const std::string& s, Iter oi) {
+    std::copy(s.begin(), s.end(), oi);
+  }
+  
+  template <typename Iter> void serialize_str(const std::string& s, Iter oi) {
+    *oi++ = '"';
+    for (std::string::const_iterator i = s.begin(); i != s.end(); ++i) {
+      switch (*i) {
+#define MAP(val, sym) case val: copy(sym, oi); break
+	MAP('"', "\\\"");
+	MAP('\\', "\\\\");
+	MAP('/', "\\/");
+	MAP('\b', "\\b");
+	MAP('\f', "\\f");
+	MAP('\n', "\\n");
+	MAP('\r', "\\r");
+	MAP('\t', "\\t");
+#undef MAP
+      default:
+	if (static_cast<unsigned char>(*i) < 0x20 || *i == 0x7f) {
+	  char buf[7];
+	  SNPRINTF(buf, sizeof(buf), "\\u%04x", *i & 0xff);
+	  copy(buf, buf + 6, oi);
+	  } else {
+	  *oi++ = *i;
+	}
+	break;
+      }
+    }
+    *oi++ = '"';
+  }
+
+  template <typename Iter> void value::serialize(Iter oi, bool prettify) const {
+    return _serialize(oi, prettify ? 0 : -1);
+  }
+  
+  inline std::string value::serialize(bool prettify) const {
+    return _serialize(prettify ? 0 : -1);
+  }
+
+  template <typename Iter> void value::_indent(Iter oi, int indent) {
+    *oi++ = '\n';
+    for (int i = 0; i < indent * INDENT_WIDTH; ++i) {
+      *oi++ = ' ';
+    }
+  }
+
+  template <typename Iter> void value::_serialize(Iter oi, int indent) const {
+    switch (type_) {
+    case string_type:
+      serialize_str(*u_.string_, oi);
+      break;
+    case array_type: {
+      *oi++ = '[';
+      if (indent != -1) {
+        ++indent;
+      }
+      for (array::const_iterator i = u_.array_->begin();
+           i != u_.array_->end();
+           ++i) {
+	if (i != u_.array_->begin()) {
+	  *oi++ = ',';
+	}
+        if (indent != -1) {
+          _indent(oi, indent);
+        }
+	i->_serialize(oi, indent);
+      }
+      if (indent != -1) {
+        --indent;
+        if (! u_.array_->empty()) {
+          _indent(oi, indent);
+        }
+      }
+      *oi++ = ']';
+      break;
+    }
+    case object_type: {
+      *oi++ = '{';
+      if (indent != -1) {
+        ++indent;
+      }
+      for (object::const_iterator i = u_.object_->begin();
+	   i != u_.object_->end();
+	   ++i) {
+	if (i != u_.object_->begin()) {
+	  *oi++ = ',';
+	}
+        if (indent != -1) {
+          _indent(oi, indent);
+        }
+	serialize_str(i->first, oi);
+	*oi++ = ':';
+        if (indent != -1) {
+          *oi++ = ' ';
+        }
+        i->second._serialize(oi, indent);
+      }
+      if (indent != -1) {
+        --indent;
+        if (! u_.object_->empty()) {
+          _indent(oi, indent);
+        }
+      }
+      *oi++ = '}';
+      break;
+    }
+    default:
+      copy(to_str(), oi);
+      break;
+    }
+    if (indent == 0) {
+      *oi++ = '\n';
+    }
+  }
+  
+  inline std::string value::_serialize(int indent) const {
+    std::string s;
+    _serialize(std::back_inserter(s), indent);
+    return s;
+  }
+  
+  template <typename Iter> class input {
+  protected:
+    Iter cur_, end_;
+    int last_ch_;
+    bool ungot_;
+    int line_;
+  public:
+    input(const Iter& first, const Iter& last) : cur_(first), end_(last), last_ch_(-1), ungot_(false), line_(1) {}
+    int getc() {
+      if (ungot_) {
+	ungot_ = false;
+	return last_ch_;
+      }
+      if (cur_ == end_) {
+	last_ch_ = -1;
+	return -1;
+      }
+      if (last_ch_ == '\n') {
+	line_++;
+      }
+      last_ch_ = *cur_ & 0xff;
+      ++cur_;
+      return last_ch_;
+    }
+    void ungetc() {
+      if (last_ch_ != -1) {
+	PICOJSON_ASSERT(! ungot_);
+	ungot_ = true;
+      }
+    }
+    Iter cur() const { return cur_; }
+    int line() const { return line_; }
+    void skip_ws() {
+      while (1) {
+	int ch = getc();
+	if (! (ch == ' ' || ch == '\t' || ch == '\n' || ch == '\r')) {
+	  ungetc();
+	  break;
+	}
+      }
+    }
+    bool expect(int expect) {
+      skip_ws();
+      if (getc() != expect) {
+	ungetc();
+	return false;
+      }
+      return true;
+    }
+    bool match(const std::string& pattern) {
+      for (std::string::const_iterator pi(pattern.begin());
+	   pi != pattern.end();
+	   ++pi) {
+	if (getc() != *pi) {
+	  ungetc();
+	  return false;
+	}
+      }
+      return true;
+    }
+  };
+  
+  template<typename Iter> inline int _parse_quadhex(input<Iter> &in) {
+    int uni_ch = 0, hex;
+    for (int i = 0; i < 4; i++) {
+      if ((hex = in.getc()) == -1) {
+	return -1;
+      }
+      if ('0' <= hex && hex <= '9') {
+	hex -= '0';
+      } else if ('A' <= hex && hex <= 'F') {
+	hex -= 'A' - 0xa;
+      } else if ('a' <= hex && hex <= 'f') {
+	hex -= 'a' - 0xa;
+      } else {
+	in.ungetc();
+	return -1;
+      }
+      uni_ch = uni_ch * 16 + hex;
+    }
+    return uni_ch;
+  }
+  
+  template<typename String, typename Iter> inline bool _parse_codepoint(String& out, input<Iter>& in) {
+    int uni_ch;
+    if ((uni_ch = _parse_quadhex(in)) == -1) {
+      return false;
+    }
+    if (0xd800 <= uni_ch && uni_ch <= 0xdfff) {
+      if (0xdc00 <= uni_ch) {
+	// a second 16-bit of a surrogate pair appeared
+	return false;
+      }
+      // first 16-bit of surrogate pair, get the next one
+      if (in.getc() != '\\' || in.getc() != 'u') {
+	in.ungetc();
+	return false;
+      }
+      int second = _parse_quadhex(in);
+      if (! (0xdc00 <= second && second <= 0xdfff)) {
+	return false;
+      }
+      uni_ch = ((uni_ch - 0xd800) << 10) | ((second - 0xdc00) & 0x3ff);
+      uni_ch += 0x10000;
+    }
+    if (uni_ch < 0x80) {
+      out.push_back(uni_ch);
+    } else {
+      if (uni_ch < 0x800) {
+	out.push_back(0xc0 | (uni_ch >> 6));
+      } else {
+	if (uni_ch < 0x10000) {
+	  out.push_back(0xe0 | (uni_ch >> 12));
+	} else {
+	  out.push_back(0xf0 | (uni_ch >> 18));
+	  out.push_back(0x80 | ((uni_ch >> 12) & 0x3f));
+	}
+	out.push_back(0x80 | ((uni_ch >> 6) & 0x3f));
+      }
+      out.push_back(0x80 | (uni_ch & 0x3f));
+    }
+    return true;
+  }
+  
+  template<typename String, typename Iter> inline bool _parse_string(String& out, input<Iter>& in) {
+    while (1) {
+      int ch = in.getc();
+      if (ch < ' ') {
+	in.ungetc();
+	return false;
+      } else if (ch == '"') {
+	return true;
+      } else if (ch == '\\') {
+	if ((ch = in.getc()) == -1) {
+	  return false;
+	}
+	switch (ch) {
+#define MAP(sym, val) case sym: out.push_back(val); break
+	  MAP('"', '\"');
+	  MAP('\\', '\\');
+	  MAP('/', '/');
+	  MAP('b', '\b');
+	  MAP('f', '\f');
+	  MAP('n', '\n');
+	  MAP('r', '\r');
+	  MAP('t', '\t');
+#undef MAP
+	case 'u':
+	  if (! _parse_codepoint(out, in)) {
+	    return false;
+	  }
+	  break;
+	default:
+	  return false;
+	}
+      } else {
+	out.push_back(ch);
+      }
+    }
+    return false;
+  }
+  
+  template <typename Context, typename Iter> inline bool _parse_array(Context& ctx, input<Iter>& in) {
+    if (! ctx.parse_array_start()) {
+      return false;
+    }
+    size_t idx = 0;
+    if (in.expect(']')) {
+      return ctx.parse_array_stop(idx);
+    }
+    do {
+      if (! ctx.parse_array_item(in, idx)) {
+	return false;
+      }
+      idx++;
+    } while (in.expect(','));
+    return in.expect(']') && ctx.parse_array_stop(idx);
+  }
+  
+  template <typename Context, typename Iter> inline bool _parse_object(Context& ctx, input<Iter>& in) {
+    if (! ctx.parse_object_start()) {
+      return false;
+    }
+    if (in.expect('}')) {
+      return true;
+    }
+    do {
+      std::string key;
+      if (! in.expect('"')
+	  || ! _parse_string(key, in)
+	  || ! in.expect(':')) {
+	return false;
+      }
+      if (! ctx.parse_object_item(in, key)) {
+	return false;
+      }
+    } while (in.expect(','));
+    return in.expect('}');
+  }
+  
+  template <typename Iter> inline std::string _parse_number(input<Iter>& in) {
+    std::string num_str;
+    while (1) {
+      int ch = in.getc();
+      if (('0' <= ch && ch <= '9') || ch == '+' || ch == '-'
+          || ch == 'e' || ch == 'E') {
+        num_str.push_back(ch);
+      } else if (ch == '.') {
+#if PICOJSON_USE_LOCALE
+        num_str += localeconv()->decimal_point;
+#else
+        num_str.push_back('.');
+#endif
+      } else {
+	in.ungetc();
+	break;
+      }
+    }
+    return num_str;
+  }
+  
+  template <typename Context, typename Iter> inline bool _parse(Context& ctx, input<Iter>& in) {
+    in.skip_ws();
+    int ch = in.getc();
+    switch (ch) {
+#define IS(ch, text, op) case ch: \
+      if (in.match(text) && op) { \
+	return true; \
+      } else { \
+	return false; \
+      }
+      IS('n', "ull", ctx.set_null());
+      IS('f', "alse", ctx.set_bool(false));
+      IS('t', "rue", ctx.set_bool(true));
+#undef IS
+    case '"':
+      return ctx.parse_string(in);
+    case '[':
+      return _parse_array(ctx, in);
+    case '{':
+      return _parse_object(ctx, in);
+    default:
+      if (('0' <= ch && ch <= '9') || ch == '-') {
+        double f;
+        char *endp;
+	in.ungetc();
+        std::string num_str = _parse_number(in);
+        if (num_str.empty()) {
+          return false;
+        }
+#ifdef PICOJSON_USE_INT64
+        {
+          errno = 0;
+          intmax_t ival = strtoimax(num_str.c_str(), &endp, 10);
+          if (errno == 0
+              && std::numeric_limits<int64_t>::min() <= ival
+              && ival <= std::numeric_limits<int64_t>::max()
+              && endp == num_str.c_str() + num_str.size()) {
+            ctx.set_int64(ival);
+            return true;
+          }
+        }
+#endif
+        f = strtod(num_str.c_str(), &endp);
+        if (endp == num_str.c_str() + num_str.size()) {
+          ctx.set_number(f);
+          return true;
+        }
+        return false;
+      }
+      break;
+    }
+    in.ungetc();
+    return false;
+  }
+  
+  class deny_parse_context {
+  public:
+    bool set_null() { return false; }
+    bool set_bool(bool) { return false; }
+#ifdef PICOJSON_USE_INT64
+    bool set_int64(int64_t) { return false; }
+#endif
+    bool set_number(double) { return false; }
+    template <typename Iter> bool parse_string(input<Iter>&) { return false; }
+    bool parse_array_start() { return false; }
+    template <typename Iter> bool parse_array_item(input<Iter>&, size_t) {
+      return false;
+    }
+    bool parse_array_stop(size_t) { return false; }
+    bool parse_object_start() { return false; }
+    template <typename Iter> bool parse_object_item(input<Iter>&, const std::string&) {
+      return false;
+    }
+  };
+  
+  class default_parse_context {
+  protected:
+    value* out_;
+  public:
+    default_parse_context(value* out) : out_(out) {}
+    bool set_null() {
+      *out_ = value();
+      return true;
+    }
+    bool set_bool(bool b) {
+      *out_ = value(b);
+      return true;
+    }
+#ifdef PICOJSON_USE_INT64
+    bool set_int64(int64_t i) {
+      *out_ = value(i);
+      return true;
+    }
+#endif
+    bool set_number(double f) {
+      *out_ = value(f);
+      return true;
+    }
+    template<typename Iter> bool parse_string(input<Iter>& in) {
+      *out_ = value(string_type, false);
+      return _parse_string(out_->get<std::string>(), in);
+    }
+    bool parse_array_start() {
+      *out_ = value(array_type, false);
+      return true;
+    }
+    template <typename Iter> bool parse_array_item(input<Iter>& in, size_t) {
+      array& a = out_->get<array>();
+      a.push_back(value());
+      default_parse_context ctx(&a.back());
+      return _parse(ctx, in);
+    }
+    bool parse_array_stop(size_t) { return true; }
+    bool parse_object_start() {
+      *out_ = value(object_type, false);
+      return true;
+    }
+    template <typename Iter> bool parse_object_item(input<Iter>& in, const std::string& key) {
+      object& o = out_->get<object>();
+      default_parse_context ctx(&o[key]);
+      return _parse(ctx, in);
+    }
+  private:
+    default_parse_context(const default_parse_context&);
+    default_parse_context& operator=(const default_parse_context&);
+  };
+
+  class null_parse_context {
+  public:
+    struct dummy_str {
+      void push_back(int) {}
+    };
+  public:
+    null_parse_context() {}
+    bool set_null() { return true; }
+    bool set_bool(bool) { return true; }
+#ifdef PICOJSON_USE_INT64
+    bool set_int64(int64_t) { return true; }
+#endif
+    bool set_number(double) { return true; }
+    template <typename Iter> bool parse_string(input<Iter>& in) {
+      dummy_str s;
+      return _parse_string(s, in);
+    }
+    bool parse_array_start() { return true; }
+    template <typename Iter> bool parse_array_item(input<Iter>& in, size_t) {
+      return _parse(*this, in);
+    }
+    bool parse_array_stop(size_t) { return true; }
+    bool parse_object_start() { return true; }
+    template <typename Iter> bool parse_object_item(input<Iter>& in, const std::string&) {
+      return _parse(*this, in);
+    }
+  private:
+    null_parse_context(const null_parse_context&);
+    null_parse_context& operator=(const null_parse_context&);
+  };
+  
+  // obsolete, use the version below
+  template <typename Iter> inline std::string parse(value& out, Iter& pos, const Iter& last) {
+    std::string err;
+    pos = parse(out, pos, last, &err);
+    return err;
+  }
+  
+  template <typename Context, typename Iter> inline Iter _parse(Context& ctx, const Iter& first, const Iter& last, std::string* err) {
+    input<Iter> in(first, last);
+    if (! _parse(ctx, in) && err != NULL) {
+      char buf[64];
+      SNPRINTF(buf, sizeof(buf), "syntax error at line %d near: ", in.line());
+      *err = buf;
+      while (1) {
+	int ch = in.getc();
+	if (ch == -1 || ch == '\n') {
+	  break;
+	} else if (ch >= ' ') {
+	  err->push_back(ch);
+	}
+      }
+    }
+    return in.cur();
+  }
+  
+  template <typename Iter> inline Iter parse(value& out, const Iter& first, const Iter& last, std::string* err) {
+    default_parse_context ctx(&out);
+    return _parse(ctx, first, last, err);
+  }
+  
+  inline std::string parse(value& out, const std::string& s) {
+    std::string err;
+    parse(out, s.begin(), s.end(), &err);
+    return err;
+  }
+
+  inline std::string parse(value& out, std::istream& is) {
+    std::string err;
+    parse(out, std::istreambuf_iterator<char>(is.rdbuf()),
+	  std::istreambuf_iterator<char>(), &err);
+    return err;
+  }
+  
+  template <typename T> struct last_error_t {
+    static std::string s;
+  };
+  template <typename T> std::string last_error_t<T>::s;
+  
+  inline void set_last_error(const std::string& s) {
+    last_error_t<bool>::s = s;
+  }
+  
+  inline const std::string& get_last_error() {
+    return last_error_t<bool>::s;
+  }
+
+  inline bool operator==(const value& x, const value& y) {
+    if (x.is<null>())
+      return y.is<null>();
+#define PICOJSON_CMP(type)					\
+    if (x.is<type>())						\
+      return y.is<type>() && x.get<type>() == y.get<type>()
+    PICOJSON_CMP(bool);
+    PICOJSON_CMP(double);
+    PICOJSON_CMP(std::string);
+    PICOJSON_CMP(array);
+    PICOJSON_CMP(object);
+#undef PICOJSON_CMP
+    PICOJSON_ASSERT(0);
+#ifdef _MSC_VER
+    __assume(0);
+#endif
+    return false;
+  }
+  
+  inline bool operator!=(const value& x, const value& y) {
+    return ! (x == y);
+  }
+}
+
+namespace std {
+  template<> inline void swap(picojson::value& x, picojson::value& y)
+    {
+      x.swap(y);
+    }
+}
+
+inline std::istream& operator>>(std::istream& is, picojson::value& x)
+{
+  picojson::set_last_error(std::string());
+  std::string err = picojson::parse(x, is);
+  if (! err.empty()) {
+    picojson::set_last_error(err);
+    is.setstate(std::ios::failbit);
+  }
+  return is;
+}
+
+inline std::ostream& operator<<(std::ostream& os, const picojson::value& x)
+{
+  x.serialize(std::ostream_iterator<char>(os));
+  return os;
+}
+#ifdef _MSC_VER
+    #pragma warning(pop)
+#endif
+
+#endif
diff --git a/src/webapi/AmuleApiConfig.cpp b/src/webapi/AmuleApiConfig.cpp
new file mode 100644
index 0000000000..a5e279b99f
--- /dev/null
+++ b/src/webapi/AmuleApiConfig.cpp
@@ -0,0 +1,499 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#include "AmuleApiConfig.h"
+
+#include <wx/file.h>
+#include <wx/fileconf.h>
+#include <wx/filefn.h>
+#include <wx/filename.h>
+#include <wx/stdpaths.h>
+#include <wx/tokenzr.h>
+#include <wx/utils.h>
+#include <wx/wfstream.h>
+
+#include <cryptopp/osrng.h>
+
+#include <cctype>
+#include <cerrno>
+#include <cstdio>
+#include <cstring>
+
+#ifndef _WIN32
+#  include <fcntl.h>
+#  include <sys/stat.h>
+#  include <unistd.h>
+#endif
+
+
+namespace {
+
+bool HexDecode(const std::string &in, std::vector<unsigned char> &out)
+{
+	if (in.size() % 2 != 0) return false;
+	out.clear();
+	out.reserve(in.size() / 2);
+	auto nibble = [](char c, unsigned &v) -> bool {
+		if (c >= '0' && c <= '9') { v = c - '0';        return true; }
+		if (c >= 'a' && c <= 'f') { v = c - 'a' + 10;   return true; }
+		if (c >= 'A' && c <= 'F') { v = c - 'A' + 10;   return true; }
+		return false;
+	};
+	for (size_t i = 0; i < in.size(); i += 2) {
+		unsigned hi, lo;
+		if (!nibble(in[i], hi) || !nibble(in[i + 1], lo)) return false;
+		out.push_back(static_cast<unsigned char>((hi << 4) | lo));
+	}
+	return true;
+}
+
+std::string HexEncode(const std::vector<unsigned char> &data)
+{
+	static const char hex[] = "0123456789abcdef";
+	std::string out;
+	out.resize(data.size() * 2);
+	for (size_t i = 0; i < data.size(); ++i) {
+		out[i * 2]     = hex[(data[i] >> 4) & 0x0F];
+		out[i * 2 + 1] = hex[ data[i]       & 0x0F];
+	}
+	return out;
+}
+
+// Trim ASCII whitespace from both ends. Used on each line of the
+// passwords file before tokenising; tolerates trailing CR (Windows-
+// edited file checked out on POSIX) and stray indentation.
+std::string Trim(const std::string &s)
+{
+	size_t a = 0;
+	while (a < s.size() && std::isspace(static_cast<unsigned char>(s[a]))) ++a;
+	size_t b = s.size();
+	while (b > a && std::isspace(static_cast<unsigned char>(s[b - 1]))) --b;
+	return s.substr(a, b - a);
+}
+
+// 32 lowercase hex chars = the canonical MD5 digest shape. Reject
+// anything else so we never store a half-typed/half-pasted line as
+// a "password".
+bool LooksLikeMd5Hex(const std::string &s)
+{
+	if (s.size() != 32) return false;
+	for (char c : s) {
+		if (!((c >= '0' && c <= '9') || (c >= 'a' && c <= 'f'))) return false;
+	}
+	return true;
+}
+
+wxString JoinPath(const wxString &dir, const wxString &leaf)
+{
+	wxFileName fn(dir, leaf);
+	return fn.GetFullPath();
+}
+
+
+// Crash-safe writer for the 0600 secret files (amuleapi-passwords,
+// amuleapi-jwt-secret). Writes the body to a sibling `<name>.tmp`,
+// fsyncs, then atomically rename(2)s onto the target. A partial write
+// or a crash mid-write leaves the original file intact — important
+// because amuleapi-passwords stores the only admin/guest credentials
+// the daemon has. Falls back to a non-atomic best-effort path on
+// Windows (POSIX rename(2) semantics aren't available there for
+// existing-target replacement).
+bool WriteFileAtomic0600(const wxString &target_path,
+                         const std::string &body)
+{
+#ifndef _WIN32
+	const std::string final_p(target_path.utf8_str());
+	const std::string tmp_p = final_p + ".tmp";
+
+	const int fd = ::open(tmp_p.c_str(),
+		O_WRONLY | O_CREAT | O_TRUNC, S_IRUSR | S_IWUSR);
+	if (fd < 0) return false;
+	::fchmod(fd, S_IRUSR | S_IWUSR);   // belt+braces against odd umasks
+
+	std::size_t written = 0;
+	while (written < body.size()) {
+		const ssize_t n = ::write(fd, body.data() + written,
+			body.size() - written);
+		if (n < 0) {
+			if (errno == EINTR) continue;
+			::close(fd);
+			::unlink(tmp_p.c_str());
+			return false;
+		}
+		written += static_cast<std::size_t>(n);
+	}
+	if (::fsync(fd) != 0) {
+		::close(fd);
+		::unlink(tmp_p.c_str());
+		return false;
+	}
+	if (::close(fd) != 0) {
+		::unlink(tmp_p.c_str());
+		return false;
+	}
+	if (::rename(tmp_p.c_str(), final_p.c_str()) != 0) {
+		::unlink(tmp_p.c_str());
+		return false;
+	}
+	return true;
+#else
+	// Windows: best-effort. wxFile::Write returns the bytes written;
+	// short writes are caught and reported.
+	wxFile f;
+	if (!f.Create(target_path, true)) return false;
+	if (body.empty()) {
+		f.Close();
+		return true;
+	}
+	const ssize_t n = f.Write(body.data(), body.size());
+	f.Close();
+	return n == static_cast<ssize_t>(body.size());
+#endif
+}
+
+}  // namespace
+
+
+wxString DefaultConfigDir()
+{
+	// Prefer the wx-standard "user data dir" — it already encapsulates
+	// the per-platform conventions amuled / amulegui use, so amuleapi
+	// drops its files alongside theirs by default. Operators with a
+	// custom amule home override the location at the CLI.
+	const wxString d = wxStandardPaths::Get().GetUserDataDir();
+	// GetUserDataDir() returns e.g. "/Users/foo/Library/Application Support/aMule"
+	// on macOS or "/home/foo/.aMule" on Linux. Both already align with
+	// where amule.conf lives.
+	return d;
+}
+
+
+bool CAmuleApiConfig::Load(const wxString &config_dir)
+{
+	m_configDir = config_dir;
+	m_lastError.clear();
+
+	if (!wxDirExists(m_configDir)) {
+		if (!wxMkdir(m_configDir, 0700)) {
+			m_lastError = "config dir does not exist and could not be created: "
+				+ std::string(m_configDir.utf8_str());
+			return false;
+		}
+	}
+
+	const wxString cfg_path     = JoinPath(m_configDir, "amuleapi.conf");
+	const wxString secret_path  = JoinPath(m_configDir, "amuleapi-jwt-secret");
+	const wxString pwfile_path  = JoinPath(m_configDir, "amuleapi-passwords");
+
+	if (!LoadAmuleapiConf(cfg_path))   return false;
+	if (!LoadJwtSecret(secret_path))   return false;
+	if (!LoadPasswords(pwfile_path))   return false;
+
+	return true;
+}
+
+
+bool CAmuleApiConfig::LoadAmuleapiConf(const wxString &path)
+{
+	const char *defaults =
+		"[Server]\n"
+		"BindAddress=127.0.0.1\n"
+		"Port=4713\n"
+		"AllowCORS=0\n"
+		"StaticRoot=\n"
+		"\n"
+		"[EC]\n"
+		"Host=127.0.0.1\n"
+		"Port=4712\n"
+		"Password=\n"
+		"\n"
+		"[Auth]\n"
+		"LoginFailureWindowSeconds=60\n"
+		"LoginFailureThreshold=5\n"
+		"LoginLockoutSeconds=300\n"
+		"\n"
+		"[Streaming]\n"
+		"EventBusRingCapacity=16384\n";
+
+	if (!wxFileExists(path)) {
+		// First-run: write mode-0600 defaults file. EC password stays
+		// empty; amuleapi refuses to connect until it's filled in.
+		// amuleapi.conf carries `[EC]/Password=` in cleartext (base
+		// class wants hashable plaintext), so owner-only mode matches
+		// jwt-secret and passwords files.
+		//
+		// WriteFileAtomic0600 (write-temp, fsync, rename) so a crash
+		// mid-write can't leave a truncated config that the next
+		// start would happily load as partial → silent default flip.
+		if (!WriteFileAtomic0600(path, std::string(defaults))) {
+			m_lastError = "cannot create amuleapi.conf: "
+				+ std::string(path.utf8_str());
+			return false;
+		}
+	}
+
+	// Enforce 0600 on every load so a hand-edit (or a `cp` from a
+	// loose-permission source) doesn't silently widen the EC
+	// password's exposure.
+	if (!EnforceOwnerOnly(path)) return false;
+
+	wxFileConfig cfg("", "", path, "",
+		wxCONFIG_USE_LOCAL_FILE | wxCONFIG_USE_RELATIVE_PATH);
+
+	wxString s;
+	long     n = 0;
+
+	if (cfg.Read("/Server/BindAddress", &s) && !s.IsEmpty()) {
+		m_server.bind_address = std::string(s.utf8_str());
+	}
+	if (cfg.Read("/Server/Port", &n) && n > 0 && n < 65536) {
+		m_server.port = static_cast<unsigned>(n);
+	}
+	{
+		long allow = 0;
+		if (cfg.Read("/Server/AllowCORS", &allow)) {
+			m_server.allow_cors = (allow != 0);
+		}
+	}
+	if (cfg.Read("/Server/CorsOriginAllowlist", &s) && !s.IsEmpty()) {
+		// Comma-separated. Trimmed; empty entries dropped.
+		wxStringTokenizer tk(s, ",");
+		while (tk.HasMoreTokens()) {
+			const wxString item = tk.GetNextToken().Trim(true).Trim(false);
+			if (!item.IsEmpty()) {
+				m_server.cors_origin_allowlist.emplace_back(item.utf8_str());
+			}
+		}
+	}
+	if (cfg.Read("/Server/StaticRoot", &s)) {
+		const wxString trimmed = s.Trim(true).Trim(false);
+		if (!trimmed.IsEmpty()) {
+			m_server.static_root = std::string(trimmed.utf8_str());
+		}
+	}
+
+	if (cfg.Read("/EC/Host", &s) && !s.IsEmpty()) {
+		m_ec.host = std::string(s.utf8_str());
+	}
+	if (cfg.Read("/EC/Port", &n) && n > 0 && n < 65536) {
+		m_ec.port = static_cast<unsigned>(n);
+	}
+	if (cfg.Read("/EC/Password", &s)) {
+		m_ec.password = std::string(s.utf8_str());
+	}
+
+	if (cfg.Read("/Auth/LoginFailureWindowSeconds", &n) && n > 0) {
+		m_auth.login_failure_window_seconds = static_cast<unsigned>(n);
+	}
+	if (cfg.Read("/Auth/LoginFailureThreshold", &n) && n > 0) {
+		m_auth.login_failure_threshold = static_cast<unsigned>(n);
+	}
+	if (cfg.Read("/Auth/LoginLockoutSeconds", &n) && n > 0) {
+		m_auth.login_lockout_seconds = static_cast<unsigned>(n);
+	}
+
+	// `[Streaming]/EventBusRingCapacity`. Below the CEventBus floor
+	// is silently clamped up by the bus itself; we just accept any
+	// positive value here.
+	if (cfg.Read("/Streaming/EventBusRingCapacity", &n) && n > 0) {
+		m_streaming.event_bus_ring_capacity = static_cast<unsigned>(n);
+	}
+
+	return true;
+}
+
+
+bool CAmuleApiConfig::LoadJwtSecret(const wxString &path)
+{
+	// Rotation is operator-manual today: delete amuleapi-jwt-secret
+	// and restart amuleapi, which auto-generates a fresh secret and
+	// invalidates every previously-issued token. A `--rotate-jwt-
+	// secret` CLI subcommand that does the file replacement + a
+	// SIGHUP reload without a full restart is roadmapped for 3.1
+	// (would let the daemon keep accepting old-keyed tokens for a
+	// grace window). Until then, the manual flow is documented in
+	// the amuleapi(1) FILES section.
+	if (!wxFileExists(path)) {
+		// Auto-generate 32 random bytes. The new file is 0600 from
+		// the moment it lands on disk (open + chmod before any data).
+		std::vector<unsigned char> secret(32, 0);
+		CryptoPP::AutoSeededRandomPool rng;
+		rng.GenerateBlock(secret.data(), secret.size());
+		if (!WriteJwtSecretFile(m_configDir, secret)) {
+			return false;
+		}
+		m_jwtSecret = std::move(secret);
+		return true;
+	}
+
+	if (!EnforceOwnerOnly(path)) return false;
+
+	wxFile f(path, wxFile::read);
+	if (!f.IsOpened()) {
+		m_lastError = "cannot open amuleapi-jwt-secret";
+		return false;
+	}
+	const wxFileOffset sz = f.Length();
+	// 64 hex chars + optional trailing newline. Cap generously to
+	// catch "someone pasted a 2 KB blob" without truncating valid
+	// edits.
+	if (sz < 64 || sz > 4096) {
+		m_lastError = "amuleapi-jwt-secret has unexpected size; "
+			"expected 64 hex chars (256-bit secret)";
+		return false;
+	}
+	std::string buf(static_cast<size_t>(sz), '\0');
+	if (f.Read(&buf[0], buf.size()) != static_cast<ssize_t>(buf.size())) {
+		m_lastError = "amuleapi-jwt-secret read failed";
+		return false;
+	}
+	const std::string trimmed = Trim(buf);
+	if (trimmed.size() != 64) {
+		m_lastError = "amuleapi-jwt-secret is not 64 hex chars after trim";
+		return false;
+	}
+	std::vector<unsigned char> decoded;
+	if (!HexDecode(trimmed, decoded) || decoded.size() != 32) {
+		m_lastError = "amuleapi-jwt-secret is not valid hex";
+		return false;
+	}
+	m_jwtSecret = std::move(decoded);
+	return true;
+}
+
+
+bool CAmuleApiConfig::LoadPasswords(const wxString &path)
+{
+	if (!wxFileExists(path)) {
+		// Auto-create empty so the operator sees the file exists, with
+		// the right mode bits. CLI flow:
+		//  amuleapi --set-admin-pass=<plain>
+		// hashes + writes the admin line; the daemon then accepts logins.
+		return WritePasswordsFile(m_configDir, "", "");
+	}
+
+	if (!EnforceOwnerOnly(path)) return false;
+
+	wxFile f(path, wxFile::read);
+	if (!f.IsOpened()) {
+		m_lastError = "cannot open amuleapi-passwords";
+		return false;
+	}
+	const wxFileOffset sz = f.Length();
+	if (sz < 0 || sz > 4096) {
+		m_lastError = "amuleapi-passwords has unexpected size";
+		return false;
+	}
+	std::string buf(static_cast<size_t>(sz), '\0');
+	if (sz > 0 && f.Read(&buf[0], buf.size()) != static_cast<ssize_t>(buf.size())) {
+		m_lastError = "amuleapi-passwords read failed";
+		return false;
+	}
+
+	std::string remainder = buf;
+	while (!remainder.empty()) {
+		const size_t nl = remainder.find('\n');
+		const std::string raw = (nl == std::string::npos)
+			? remainder
+			: remainder.substr(0, nl);
+		remainder = (nl == std::string::npos) ? std::string()
+		                                       : remainder.substr(nl + 1);
+
+		const std::string line = Trim(raw);
+		if (line.empty() || line[0] == '#') continue;
+		const size_t eq = line.find('=');
+		if (eq == std::string::npos) {
+			m_lastError = "amuleapi-passwords: malformed line (no '=')";
+			return false;
+		}
+		const std::string key = Trim(line.substr(0, eq));
+		const std::string val = Trim(line.substr(eq + 1));
+		if (val.empty()) continue;   // role explicitly disabled
+		if (!LooksLikeMd5Hex(val)) {
+			m_lastError = "amuleapi-passwords: value for '" + key +
+				"' is not 32 lowercase hex chars";
+			return false;
+		}
+		if      (key == "admin") m_adminPasswordMd5 = val;
+		else if (key == "guest") m_guestPasswordMd5 = val;
+		else {
+			m_lastError = "amuleapi-passwords: unknown key '" + key + "'";
+			return false;
+		}
+	}
+	return true;
+}
+
+
+bool CAmuleApiConfig::EnforceOwnerOnly(const wxString &path)
+{
+#ifdef _WIN32
+	(void)path;
+	return true;
+#else
+	struct stat st;
+	const std::string p(path.utf8_str());
+	if (stat(p.c_str(), &st) != 0) {
+		m_lastError = "stat failed for " + p;
+		return false;
+	}
+	if ((st.st_mode & 0077) != 0) {
+		char buf[256];
+		std::snprintf(buf, sizeof(buf),
+			"%s has mode 0%o; expected 0600 (owner read/write only). "
+			"Fix with: chmod 600 \"%s\"",
+			p.c_str(), st.st_mode & 0777, p.c_str());
+		m_lastError = buf;
+		return false;
+	}
+	return true;
+#endif
+}
+
+
+bool CAmuleApiConfig::WritePasswordsFile(const wxString &config_dir,
+                                         const std::string &admin_md5,
+                                         const std::string &guest_md5)
+{
+	const wxString path = JoinPath(config_dir, "amuleapi-passwords");
+	std::string body;
+	if (!admin_md5.empty()) body += "admin=" + admin_md5 + "\n";
+	if (!guest_md5.empty()) body += "guest=" + guest_md5 + "\n";
+	if (!WriteFileAtomic0600(path, body)) return false;
+	if (!admin_md5.empty()) m_adminPasswordMd5 = admin_md5;
+	if (!guest_md5.empty()) m_guestPasswordMd5 = guest_md5;
+	return true;
+}
+
+
+bool CAmuleApiConfig::WriteJwtSecretFile(const wxString &config_dir,
+                                         const std::vector<unsigned char> &secret_32)
+{
+	if (secret_32.size() != 32) {
+		m_lastError = "WriteJwtSecretFile: expected 32 bytes";
+		return false;
+	}
+	const wxString path = JoinPath(config_dir, "amuleapi-jwt-secret");
+	return WriteFileAtomic0600(path, HexEncode(secret_32) + "\n");
+}
diff --git a/src/webapi/AmuleApiConfig.h b/src/webapi/AmuleApiConfig.h
new file mode 100644
index 0000000000..e01a911a3a
--- /dev/null
+++ b/src/webapi/AmuleApiConfig.h
@@ -0,0 +1,157 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#ifndef WEBAPI_CONFIG_H
+#define WEBAPI_CONFIG_H
+
+#include <string>
+#include <vector>
+
+#include <wx/string.h>
+
+
+// amuleapi's three on-disk config files (in the user's amule config
+// dir; independent of remote.conf):
+//
+//   amuleapi.conf         INI — HTTP bind + port + EC connection
+//                         params + auth tunables
+//   amuleapi-jwt-secret   raw hex (64 chars + \n) — HMAC-SHA-256 key
+//   amuleapi-passwords    two-line text — admin=<md5> / guest=<md5>
+//
+// `amuleapi-jwt-secret` is auto-generated with 32 random bytes on
+// first run. `amuleapi-passwords` may be empty (daemon refuses
+// /auth/login until at least one role is set via
+// `amuleapi --set-admin-pass=...`). `amuleapi.conf` is created
+// from defaults if missing.
+//
+// POSIX: both secret files must be 0600; looser bits → daemon
+// refuses to start with an actionable error. Windows has no
+// equivalent enforcement (QUICKSTART covers ACL mitigation).
+
+class CAmuleApiConfig {
+public:
+	struct Server {
+		std::string bind_address    = "127.0.0.1";
+		unsigned    port            = 4713;
+		bool        allow_cors      = false;
+		std::vector<std::string> cors_origin_allowlist;
+		// Filesystem root of a bundled web frontend. Empty (default) =
+		// API-only deployment: non-/api/ paths return 404. Non-empty =
+		// the daemon serves GET/HEAD requests for paths outside /api/
+		// from this directory, with an index.html SPA fallback for
+		// extension-less misses. See ServeStaticFile in Api.cpp.
+		std::string static_root;
+	};
+
+	struct Ec {
+		std::string host     = "127.0.0.1";
+		unsigned    port     = 4712;
+		std::string password;   // matches amuled's [ExternalConnect]/Password
+	};
+
+	struct Auth {
+		unsigned login_failure_window_seconds = 60;
+		unsigned login_failure_threshold      = 5;
+		unsigned login_lockout_seconds        = 300;
+	};
+
+	struct Streaming {
+		// SSE ring capacity. Sized for a cold-start tick on a busy
+		// node (5K downloads + 5K shared can publish ~10K `*_added`
+		// in one tick before any subscriber drains). Values below
+		// the CEventBus::kMinCapacity floor are clamped up at the
+		// bus level so an operator can't accidentally disable
+		// replay. Operators with very heavy nodes can raise this;
+		// memory ≈ capacity × ~1 KB JSON payload.
+		unsigned event_bus_ring_capacity = 16384;
+	};
+
+	// Bring everything into memory from `config_dir`. Returns true on
+	// success; false on missing required field, mode-bit failure, or
+	// malformed INI. On failure, the human-readable reason is left in
+	// LastError() so the caller can surface it via Show(...).
+	bool Load(const wxString &config_dir);
+
+	const wxString    &ConfigDir()    const { return m_configDir; }
+	const Server      &ServerCfg()    const { return m_server; }
+	const Ec          &EcCfg()        const { return m_ec; }
+	const Auth        &AuthCfg()      const { return m_auth; }
+	const Streaming   &StreamingCfg() const { return m_streaming; }
+
+	// Raw HMAC secret (32 bytes when loaded from a valid 64-char
+	// hex file). May be reloaded from disk via Load(...).
+	const std::vector<unsigned char> &JwtSecret() const { return m_jwtSecret; }
+
+	// MD5 hex digests for the two roles. Empty when the corresponding
+	// line is absent from amuleapi-passwords — `/auth/login` returns
+	// `login_disabled` for that role.
+	const std::string &AdminPasswordMd5() const { return m_adminPasswordMd5; }
+	const std::string &GuestPasswordMd5() const { return m_guestPasswordMd5; }
+
+	const std::string &LastError() const { return m_lastError; }
+
+	// Test/CLI helpers — used by `amuleapi --set-admin-pass=...` and
+	// the unit test. Writes the file with mode 0600; the caller is
+	// responsible for hashing the plaintext to MD5 hex first.
+	bool WritePasswordsFile(const wxString &config_dir,
+	                        const std::string &admin_md5,
+	                        const std::string &guest_md5);
+
+	bool WriteJwtSecretFile(const wxString &config_dir,
+	                        const std::vector<unsigned char> &secret_32);
+
+private:
+	bool LoadAmuleapiConf(const wxString &path);
+	bool LoadJwtSecret(const wxString &path);
+	bool LoadPasswords(const wxString &path);
+
+	// POSIX-only mode check. Returns true on Windows (no enforcement
+	// possible) or when the file matches 0600. Sets m_lastError on
+	// failure.
+	bool EnforceOwnerOnly(const wxString &path);
+
+	wxString    m_configDir;
+	Server      m_server;
+	Ec          m_ec;
+	Auth        m_auth;
+	Streaming   m_streaming;
+	std::vector<unsigned char> m_jwtSecret;
+	std::string m_adminPasswordMd5;
+	std::string m_guestPasswordMd5;
+
+	std::string m_lastError;
+};
+
+
+// Canonical config dir per platform. Mirrors amule's own
+// GetUserDataDir() but without the dependency on `amule.h` — amuleapi
+// runs standalone and can't pull in the GUI/daemon-side helpers.
+//
+// POSIX (XDG):    ${XDG_CONFIG_HOME:-$HOME/.config}/aMule
+//  macOS:          $HOME/Library/Application Support/aMule
+//  Windows:        %APPDATA%/aMule
+wxString DefaultConfigDir();
+
+
+#endif // WEBAPI_CONFIG_H
diff --git a/src/webapi/Api.cpp b/src/webapi/Api.cpp
new file mode 100644
index 0000000000..1fd7bade7b
--- /dev/null
+++ b/src/webapi/Api.cpp
@@ -0,0 +1,5170 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#include "Api.h"
+
+#include "config.h"        // AMULEAPI_STATIC_DIR (compile-time install path)
+#include "AmuleApiConfig.h"
+#include "App.h"
+#include "Auth.h"
+#include "ConstantTime.h"
+#include "Etag.h"
+#include "JsonWriter.h"
+#include "Jwt.h"
+#include "PathPatterns.h"
+#include "Refresher.h"    // ParseStatsTreeFromPacket / ParseGraphsFromPacket / ApplySearchFull
+#include "StaticFs.h"     // IsDir, ResolveWithinRoot
+#include "State.h"
+
+#include "Constants.h"
+
+#include <ec/cpp/ECPacket.h>
+#include <ec/cpp/ECCodes.h>
+#include <ec/cpp/ECSpecialTags.h>
+
+#include <wx/stdpaths.h>
+#include <wx/filename.h>
+#ifdef __WXMAC__
+#include <CoreFoundation/CoreFoundation.h>
+#include <CoreServices/CoreServices.h>
+#include <wx/osx/core/cfstring.h>
+#endif
+
+#include <algorithm>
+#include <cerrno>
+#include <fstream>
+#include <set>
+#include <sstream>
+#include <cctype>
+#include <climits>
+#include <cstdlib>
+#include <sys/stat.h>
+
+// strncasecmp lives in <strings.h> on POSIX (glibc also exposes it
+// via <string.h>, but musl/BSDs don't). Match the shim
+// libwebcommon/HeaderParse.cpp ships.
+#ifdef _WIN32
+#  define strncasecmp _strnicmp
+#else
+#  include <strings.h>
+#endif
+
+#define PICOJSON_USE_INT64
+#include "picojson.h"
+
+#include "config.h"     // VERSION
+
+#include "Types.h"     // uint8 (required by libs/common/MD5Sum.h)
+#include <common/MD5Sum.h>
+
+#include <wx/string.h>
+
+#include <cstdio>
+#include <ctime>
+
+
+namespace {
+
+void SplitPathAndQuery(const std::string &target,
+                       std::string &path,
+                       std::string &query)
+{
+	const size_t q = target.find('?');
+	if (q == std::string::npos) {
+		path  = target;
+		query = std::string();
+	} else {
+		path  = target.substr(0, q);
+		query = target.substr(q + 1);
+	}
+}
+
+
+CHttpServer::Response ErrorResponse(unsigned status,
+                                    const char *code,
+                                    const char *message)
+{
+	CHttpServer::Response r;
+	r.status       = status;
+	r.content_type = "application/json";
+	CJsonWriter w;
+	w.BeginObject();
+	  w.Key("error");
+	  w.BeginObject();
+	    w.Key("code");    w.ValueString(wxString::FromAscii(code));
+	    w.Key("message"); w.ValueString(wxString::FromAscii(message));
+	  w.EndObject();
+	w.EndObject();
+	const wxString js = w.GetBuffer();
+	const wxScopedCharBuffer ub = js.utf8_str();
+	r.body.assign(ub.data(), ub.length());
+	return r;
+}
+
+
+// Common preamble for every auth-protected endpoint. Pulls the JWT
+// out of either the Authorization header or the cookie, verifies it,
+// rejects revoked tokens, and exposes the resulting VerifyResult.
+// Returns 401 on any failure.
+//
+// Token precedence: Authorization header wins over the cookie when
+// both are present. This mirrors the convention browsers and SDKs
+// already converge on — a client that explicitly attached a bearer
+// header signalled intent that overrides the implicit cookie.
+struct AuthOutcome {
+	bool                   ok    = false;
+	CHttpServer::Response  rejection;
+	CJwt::VerifyResult     verified;
+};
+
+AuthOutcome AuthenticateRequest(const CHttpServer::Request &req,
+                                CJwt                       &jwt,
+                                webapi::CRevocationSet     &revocations,
+                                const std::string          &cookie_name)
+{
+	AuthOutcome out;
+
+	std::string token;
+	auto auth_it = req.headers.find("Authorization");
+	if (auth_it == req.headers.end()) {
+		// Case-tolerant fallback: HTTP header names are case-insensitive,
+		// but Beast preserves whatever the client sent — so a lowercase
+		// `authorization:` from a curl `-H` slips past the literal find.
+		// Walk the map once to recover.
+		for (const auto &h : req.headers) {
+			if (h.first.size() == 13
+			    && strncasecmp(h.first.c_str(), "Authorization", 13) == 0) {
+				auth_it = req.headers.find(h.first);
+				break;
+			}
+		}
+	}
+	if (auth_it != req.headers.end()) {
+		token = webapi::ExtractBearerToken(auth_it->second);
+	}
+	if (token.empty()) {
+		// No Authorization → fall through to the cookie. Browser-driven
+		// session-cookie clients land here; bearer-only API clients
+		// already have their token from the header path above.
+		auto ck_it = req.headers.find("Cookie");
+		if (ck_it == req.headers.end()) {
+			for (const auto &h : req.headers) {
+				if (h.first.size() == 6
+				    && strncasecmp(h.first.c_str(), "Cookie", 6) == 0) {
+					ck_it = req.headers.find(h.first);
+					break;
+				}
+			}
+		}
+		if (ck_it != req.headers.end()) {
+			token = webapi::ExtractCookieValue(ck_it->second, cookie_name);
+		}
+	}
+	if (token.empty()) {
+		out.rejection = ErrorResponse(401, "unauthorized",
+			"missing bearer token or session cookie");
+		return out;
+	}
+	if (!jwt.Verify(token, out.verified)) {
+		out.rejection = ErrorResponse(401, "unauthorized",
+			"invalid or expired token");
+		return out;
+	}
+	if (revocations.IsRevoked(out.verified.jti)) {
+		out.rejection = ErrorResponse(401, "unauthorized",
+			"token has been revoked");
+		return out;
+	}
+	out.ok = true;
+	return out;
+}
+
+
+// Wrapper that pipes AuthenticateRequest through a per-IP failure
+// counter. Every 401 (missing token / bad sig / expired / revoked)
+// counts against the calling IP; once the bucket fills the IP gets
+// 429 with Retry-After until the lockout window expires. Pre-checks
+// the bucket BEFORE Verify() so a locked-out IP can't burn CPU on
+// MAC compares either. Used by every auth-protected handler — login
+// keeps its own m_rateLimiter for the dedicated password-failure
+// path.
+AuthOutcome AuthenticateRequestRateLimited(
+	const CHttpServer::Request &req,
+	CJwt                       &jwt,
+	webapi::CRevocationSet     &revocations,
+	webapi::CRateLimiter       &limiter,
+	const std::string          &cookie_name)
+{
+	AuthOutcome out;
+	const std::string &ip = req.remote_addr;
+
+	const auto decision = limiter.Check(ip);
+	if (decision.locked_out) {
+		CHttpServer::Response r = ErrorResponse(429, "rate_limited",
+			"too many failed auth attempts; retry later");
+		char retry_after[32];
+		std::snprintf(retry_after, sizeof(retry_after), "%lld",
+			static_cast<long long>(decision.retry_after_seconds));
+		r.headers["Retry-After"] = retry_after;
+		out.rejection = std::move(r);
+		return out;
+	}
+
+	out = AuthenticateRequest(req, jwt, revocations, cookie_name);
+	if (out.ok) {
+		limiter.NoteSuccess(ip);
+	} else {
+		limiter.NoteFailure(ip);
+	}
+	return out;
+}
+
+
+// `Set-Cookie: <name>=<value>; HttpOnly; SameSite=Strict; Path=/api/v0;
+//             Max-Age=<lifetime>`
+//
+// No `Secure`: amuleapi serves HTTP by design (operator terminates
+// TLS in front). Documented in QUICKSTART.
+//
+// Attributes shared by Set-Cookie (login) + clear-cookie (logout):
+// RFC 6265 §5.3 requires (name, path, domain) match to delete, so
+// one shared constant keeps the two paths from drifting.
+const char *const kSessionCookieAttrs =
+	"; HttpOnly; SameSite=Strict; Path=/api/v0";
+
+std::string MakeSetCookie(const std::string &name,
+                          const std::string &value,
+                          std::time_t expires_at)
+{
+	const std::time_t now      = std::time(nullptr);
+	// Boundary case: an already-expired `expires_at` produces
+	// `Max-Age=0`, which makes the browser delete the cookie on
+	// receipt (RFC 6265 §5.2.2). That's the right behaviour — issuing
+	// an expired token's cookie shouldn't grant the client a working
+	// session — so we emit it deliberately rather than clamping to
+	// some positive minimum.
+	const std::time_t lifetime = expires_at > now ? expires_at - now : 0;
+	// std::string instead of a fixed snprintf buffer. The previous
+	// 256-byte buffer fit today's ~189-byte HS256 JWT plus the
+	// attribute boilerplate with room to spare, but any future
+	// payload extension (extra claim, longer secret, switch to a
+	// longer alg) would silently truncate. std::string sizes
+	// itself.
+	std::string out;
+	out.reserve(name.size() + value.size() + 80);
+	out += name;
+	out += '=';
+	out += value;
+	out += kSessionCookieAttrs;
+	out += "; Max-Age=";
+	out += std::to_string(static_cast<long long>(lifetime));
+	return out;
+}
+
+
+// `Set-Cookie: <name>=; ... Max-Age=0` — invalidates whatever was
+// set on a prior login. Used by /auth/logout. MUST use the same
+// (name, path, domain) tuple as MakeSetCookie or the browser
+// won't drop the original.
+std::string MakeClearCookie(const std::string &name)
+{
+	std::string out;
+	out.reserve(name.size() + 64);
+	out += name;
+	out += '=';
+	out += kSessionCookieAttrs;
+	out += "; Max-Age=0";
+	return out;
+}
+
+
+// `amuleapi_token` namespacing keeps the cookie distinct from
+// amuleweb's legacy `amule_token` so the two daemons can coexist
+// behind the same host without a Set-Cookie tug-of-war.
+const char *const kSessionCookieName = "amuleapi_token";
+
+
+// Hard ceiling for individual static-asset reads. Frontend bundles are
+// kilobytes to a few MB; 16 MiB is comfortable headroom while keeping a
+// malformed StaticRoot pointing at /dev/zero or a multi-GB log file
+// from exhausting daemon RAM.
+constexpr std::size_t kStaticMaxFileBytes = 16 * 1024 * 1024;
+
+
+// Map file extension to Content-Type. Unknown → application/octet-stream
+// (no XSS amplification from a wrong-type response on an attacker-named
+// file).
+std::string StaticContentType(const std::string &path)
+{
+	const std::size_t dot = path.find_last_of('.');
+	if (dot == std::string::npos) return "application/octet-stream";
+	std::string ext = path.substr(dot + 1);
+	for (char &c : ext) c = static_cast<char>(std::tolower(
+		static_cast<unsigned char>(c)));
+	if (ext == "html" || ext == "htm") return "text/html; charset=utf-8";
+	if (ext == "js"  || ext == "mjs")  return "text/javascript; charset=utf-8";
+	if (ext == "css")  return "text/css; charset=utf-8";
+	if (ext == "json") return "application/json; charset=utf-8";
+	if (ext == "svg")  return "image/svg+xml";
+	if (ext == "png")  return "image/png";
+	if (ext == "gif")  return "image/gif";
+	if (ext == "jpg" || ext == "jpeg") return "image/jpeg";
+	if (ext == "ico")  return "image/x-icon";
+	if (ext == "webp") return "image/webp";
+	if (ext == "woff2") return "font/woff2";
+	if (ext == "woff")  return "font/woff";
+	if (ext == "ttf")   return "font/ttf";
+	if (ext == "map")  return "application/json";
+	if (ext == "txt")  return "text/plain; charset=utf-8";
+	return "application/octet-stream";
+}
+
+
+// Slurp `fs_path` into `out`. Returns false if the path is not a
+// regular file, exceeds kStaticMaxFileBytes, or any read error. `st`
+// is populated on success so the caller can derive an ETag from
+// mtime + size without re-stat'ing.
+bool ReadStaticFile(const std::string &fs_path, std::string &out,
+                    struct stat &st)
+{
+	if (::stat(fs_path.c_str(), &st) != 0) return false;
+	if (!S_ISREG(st.st_mode)) return false;
+	if (static_cast<std::size_t>(st.st_size) > kStaticMaxFileBytes) return false;
+	std::ifstream f(fs_path.c_str(), std::ios::binary);
+	if (!f.is_open()) return false;
+	std::ostringstream ss;
+	ss << f.rdbuf();
+	if (f.bad()) return false;
+	out = ss.str();
+	return true;
+}
+
+
+// "mtime-size" hex ETag — same shape nginx defaults to. Strong-form
+// quoted per RFC 7232. Sufficient for the local-frontend case where
+// the daemon and the file system are colocated and clock-sane.
+std::string BuildStaticEtag(const struct stat &st)
+{
+	std::ostringstream oss;
+	oss << '"' << std::hex
+	    << static_cast<std::uint64_t>(st.st_mtime) << '-'
+	    << static_cast<std::uint64_t>(st.st_size) << '"';
+	return oss.str();
+}
+
+
+// Resolve the default static directory when amuleapi.conf's
+// [Server]/StaticRoot is empty. Mirrors amuleweb's GetTemplateDir
+// (src/webserver/src/WebInterface.cpp): try the macOS .app bundle's
+// Resources/ first (so an installed aMule.app surfaces the bundled
+// frontend without a conf edit), then the compile-time install path
+// from AMULEAPI_STATIC_DIR, then wxStandardPaths' platform-adjusted
+// resource dir. Returns the first existing directory; empty if none.
+std::string ResolveDefaultStaticDir()
+{
+	const std::string asset = "amuleapi-static";
+
+#ifdef __WXMAC__
+	// LaunchServices lookup for the installed aMule.app. Picks up the
+	// bundled placeholder when the operator launched amuleapi from a
+	// path-registered .app install.
+	CFArrayRef urls = LSCopyApplicationURLsForBundleIdentifier(
+		CFSTR("org.amule.aMule"), NULL);
+	CFURLRef bundle_url = NULL;
+	if (urls) {
+		if (CFArrayGetCount(urls) > 0) {
+			bundle_url = (CFURLRef)CFRetain(
+				CFArrayGetValueAtIndex(urls, 0));
+		}
+		CFRelease(urls);
+	}
+	if (bundle_url) {
+		CFBundleRef bundle = CFBundleCreate(NULL, bundle_url);
+		CFRelease(bundle_url);
+		if (bundle) {
+			CFStringRef name = CFStringCreateWithCString(
+				NULL, asset.c_str(), kCFStringEncodingUTF8);
+			CFURLRef rsrc = CFBundleCopyResourceURL(
+				bundle, name, NULL, NULL);
+			CFRelease(name);
+			CFRelease(bundle);
+			if (rsrc) {
+				CFURLRef abs = CFURLCopyAbsoluteURL(rsrc);
+				CFRelease(rsrc);
+				if (abs) {
+					CFStringRef p = CFURLCopyFileSystemPath(
+						abs, kCFURLPOSIXPathStyle);
+					CFRelease(abs);
+					std::string s =
+						std::string(wxCFStringRef(p).AsString().utf8_str());
+					if (webapi::IsDir(s)) return s;
+				}
+			}
+		}
+	}
+#endif  // __WXMAC__
+
+#ifdef AMULEAPI_STATIC_DIR
+	if (webapi::IsDir(AMULEAPI_STATIC_DIR)) {
+		return std::string(AMULEAPI_STATIC_DIR);
+	}
+#endif
+
+	// wxStandardPaths fallback. Same platform adjustments amuleweb
+	// applies for its `webserver/` lookup (WebInterface.cpp:211-225).
+	wxString dir = wxStandardPaths::Get().GetResourcesDir();
+#if defined(__WINDOWS__)
+	// Installer layout: bin\amuleapi.exe + share\amule\amuleapi-static\.
+	// wxStandardPaths returns the exe directory on Windows, so go up
+	// one level and into the FHS-style share/amule/ tree.
+	dir = wxFileName(dir, "..").GetFullPath();
+	dir = wxFileName(dir, "share").GetFullPath();
+	dir = wxFileName(dir, "amule").GetFullPath();
+#elif !defined(__WXMAC__)
+	dir = dir.BeforeLast(wxFileName::GetPathSeparator());
+	dir = wxFileName(dir, "amule").GetFullPath();
+#endif
+	dir = wxFileName(dir, asset).GetFullPath();
+	const std::string s(dir.utf8_str());
+	if (webapi::IsDir(s)) return s;
+	return std::string();
+}
+
+
+}  // namespace
+
+
+CApiDispatcher::CApiDispatcher(const CAmuleApiConfig &config,
+                               CJwt                  &jwt,
+                               webapi::CState        &state,
+                               CamuleapiApp          &app)
+	: m_config(config),
+	  m_jwt(jwt),
+	  m_state(state),
+	  m_app(app),
+	  m_rateLimiter(webapi::CRateLimiter::Config{
+		config.AuthCfg().login_failure_window_seconds,
+		config.AuthCfg().login_failure_threshold,
+		config.AuthCfg().login_lockout_seconds}),
+	  // Generic-401 limiter: 30 failures within 60 s, 5-minute
+	  // lockout. Hard-coded for now — operators have a separate
+	  // knob for login-specific limits; the generic 401 cap is a
+	  // crash-pad against credential-stuffing across all non-
+	  // login endpoints and can become a config knob in 3.1 if
+	  // anyone asks.
+	  m_authRateLimiter(webapi::CRateLimiter::Config{
+		60u, 30u, 300u})
+{
+}
+
+
+namespace {
+
+// Case-tolerant header lookup. Beast preserves the wire-form casing
+// the client sent, so a literal `req.headers.find("If-None-Match")`
+// misses lowercased headers. Walks the map once on miss to recover.
+std::string FindHeaderCaseInsensitive(
+	const std::map<std::string, std::string> &headers,
+	const std::string &name)
+{
+	auto it = headers.find(name);
+	if (it != headers.end()) return it->second;
+	for (const auto &h : headers) {
+		if (h.first.size() == name.size()
+		    && strncasecmp(h.first.c_str(), name.c_str(),
+		                   name.size()) == 0) {
+			return h.second;
+		}
+	}
+	return std::string();
+}
+
+
+// resolve the CORS Origin echo for this request. Returns
+// the verbatim Origin to put in `Access-Control-Allow-Origin`, or
+// an empty string when CORS is disabled, the request had no Origin
+// (same-origin browser navigation; non-browser caller), or the
+// allowlist rejected the value. Wildcard semantics: `allow_cors=1`
+// with an empty allowlist echoes the request's Origin verbatim,
+// which is `*`-equivalent but cookie-auth-compatible (the literal
+// `*` is incompatible with `Access-Control-Allow-Credentials: true`
+// per CORS Fetch §3.2.5).
+std::string ResolveCorsOrigin(const CHttpServer::Request &req,
+                              const CAmuleApiConfig &cfg)
+{
+	if (!cfg.ServerCfg().allow_cors) return std::string();
+	const std::string origin = FindHeaderCaseInsensitive(
+		req.headers, "Origin");
+	if (origin.empty()) return std::string();
+	const auto &list = cfg.ServerCfg().cors_origin_allowlist;
+	if (list.empty()) return origin;          // echo any origin
+	for (const auto &allowed : list) {
+		if (allowed == origin) return origin;
+	}
+	return std::string();
+}
+
+
+// stamp the resolved CORS headers onto a response. `Vary:
+// Origin` is ALWAYS added when CORS is enabled (even on rejected
+// origins) so intermediaries don't cache a cross-origin response
+// against a same-origin cache key. The auth + content headers go
+// on iff the origin was actually allowed.
+void ApplyCorsHeaders(std::map<std::string, std::string> &headers,
+                      const std::string &resolved_origin,
+                      bool cors_enabled)
+{
+	if (!cors_enabled) return;
+	headers["Vary"] = "Origin";
+	if (resolved_origin.empty()) return;
+	headers["Access-Control-Allow-Origin"]      = resolved_origin;
+	headers["Access-Control-Allow-Credentials"] = "true";
+	// Header names the client may read from `fetch().headers.get(...)`
+	// — by default the Fetch spec only exposes the CORS-safelisted
+	// response headers (Cache-Control, Content-Language, Content-Type,
+	// Expires, Last-Modified, Pragma). amuleapi clients want to read
+	// ETag for cache validation; SSE clients don't need this list.
+	headers["Access-Control-Expose-Headers"]    = "ETag";
+}
+
+
+// Forward declaration so HandleLogin (which sits above the helper's
+// definition) can share the depth-cap defence. The definition lives
+// near the other mutation-body parsers further down the file.
+bool ParseJsonObjectBody(const std::string &body, picojson::value &out,
+                         std::string &err);
+
+}  // namespace
+
+
+CHttpServer::Response CApiDispatcher::Dispatch(const CHttpServer::Request &req)
+{
+	const bool cors_enabled    = m_config.ServerCfg().allow_cors;
+	const std::string cors_org = ResolveCorsOrigin(req, m_config);
+
+	// CORS preflight short-circuit. OPTIONS requests with
+	// `Access-Control-Request-Method` are browser preflights — they
+	// don't carry credentials and shouldn't run the auth gate or the
+	// route handler. Reply with 204 and the CORS bundle (or 204 +
+	// `Vary: Origin` only when the origin is rejected — the browser
+	// blocks the subsequent real request).
+	if (req.method == "OPTIONS"
+	    && !FindHeaderCaseInsensitive(req.headers,
+	                                  "Access-Control-Request-Method").empty()) {
+		CHttpServer::Response pre;
+		pre.status       = 204;
+		pre.content_type.clear();
+		ApplyCorsHeaders(pre.headers, cors_org, cors_enabled);
+		if (!cors_org.empty()) {
+			pre.headers["Access-Control-Allow-Methods"] =
+				"GET, HEAD, POST, PATCH, DELETE, OPTIONS";
+			// Headers actual requests may send. Authorization for
+			// bearer; If-None-Match for ETag conditional GET;
+			// Last-Event-ID for SSE replay.
+			pre.headers["Access-Control-Allow-Headers"] =
+				"Authorization, Content-Type, If-None-Match, Last-Event-ID";
+			pre.headers["Access-Control-Max-Age"] = "86400";
+		}
+		return pre;
+	}
+
+	// post-process every response with an ETag stamp +
+	// `If-None-Match` → 304 swap, but only on GET/HEAD that come back
+	// 200. Mutations (POST/PATCH/DELETE) and error paths are passed
+	// through unchanged — there's no benefit to ETag-caching a 4xx
+	// body, and a mutation's response carries the post-mutation
+	// state which the client always wants delivered.
+	CHttpServer::Response resp = DispatchToHandler(req);
+
+	const bool is_safe_method = (req.method == "GET" || req.method == "HEAD");
+	if (is_safe_method && resp.status == 200 && !resp.body.empty()) {
+		// Snapshot-versioned memoization: skip the MD5 over the
+		// (potentially multi-MB) body when the (target,
+		// snapshot_at) tuple matches what we already hashed.
+		const std::time_t snap = m_state.SnapshotAt();
+		std::string etag;
+		{
+			std::lock_guard<std::mutex> g(m_etagCacheMu);
+			auto it = m_etagCache.find(req.target);
+			if (it != m_etagCache.end()
+			    && it->second.snapshot_at == snap
+			    && snap != 0) {
+				etag = it->second.etag;
+			}
+		}
+		if (etag.empty()) {
+			etag = webcommon::Etag(resp.body);
+			std::lock_guard<std::mutex> g(m_etagCacheMu);
+			if (m_etagCache.size() >= kEtagCacheCapacity) {
+				// Crude memory backstop. Real workload is a few
+				// dozen unique targets; the wholesale clear is
+				// cheaper than a real LRU machinery.
+				m_etagCache.clear();
+			}
+			EtagCacheEntry e;
+			e.snapshot_at = snap;
+			e.etag        = etag;
+			m_etagCache[req.target] = std::move(e);
+		}
+		// RFC 7232 §2.3 — the header value MUST be quoted.
+		resp.headers["ETag"] = "\"" + etag + "\"";
+
+		const std::string inm = FindHeaderCaseInsensitive(
+			req.headers, "If-None-Match");
+		if (webcommon::IfNoneMatchHits(inm, etag)) {
+			// 304 carries no body and no Content-Type, but the ETag
+			// header IS preserved (RFC 7232 §4.1 — clients use it to
+			// re-stamp the cached representation).
+			resp.status = 304;
+			resp.body.clear();
+			resp.content_type.clear();
+		}
+		// HEAD never carries a body — the inner handler already shaped
+		// the response body for the GET path; strip it now. The ETag
+		// header is preserved so HEAD-based cache validators work.
+		if (req.method == "HEAD") {
+			resp.body.clear();
+		}
+	}
+
+	// stamp CORS on every response (success and error paths)
+	// so browsers can read the body in the 4xx/5xx case too.
+	ApplyCorsHeaders(resp.headers, cors_org, cors_enabled);
+	return resp;
+}
+
+
+CHttpServer::Response CApiDispatcher::DispatchToHandler(const CHttpServer::Request &req)
+{
+	std::string path, query;
+	SplitPathAndQuery(req.target, path, query);
+
+	// Defence-in-depth: reject NUL / encoded NUL / encoded `..` /
+	// literal `..` segments before routing. Today's byte-exact
+	// routes 404 these requests organically, but adding a future
+	// endpoint that admits path captures (file-by-name, log-by-
+	// label, …) would silently inherit a traversal surface without
+	// this gate.
+	if (web_api_path::LooksMalicious(path)) {
+		return ErrorResponse(400, "bad_request",
+			"path contains a traversal/injection token");
+	}
+
+	if (path == "/api/v0/version") {
+		if (req.method != "GET" && req.method != "HEAD") {
+			return ErrorResponse(405, "method_not_allowed",
+				"method not allowed on /api/v0/version");
+		}
+		return HandleVersion(req);
+	}
+
+	if (path == "/api/v0/auth/login") {
+		if (req.method != "POST") {
+			return ErrorResponse(405, "method_not_allowed",
+				"only POST on /auth/login");
+		}
+		return HandleLogin(req);
+	}
+
+	if (path == "/api/v0/auth/logout") {
+		if (req.method != "POST") {
+			return ErrorResponse(405, "method_not_allowed",
+				"only POST on /auth/logout");
+		}
+		return HandleLogout(req);
+	}
+
+	if (path == "/api/v0/auth/session") {
+		if (req.method != "GET" && req.method != "HEAD") {
+			return ErrorResponse(405, "method_not_allowed",
+				"only GET on /auth/session");
+		}
+		return HandleSession(req);
+	}
+
+	if (path == "/api/v0/status") {
+		if (req.method != "GET" && req.method != "HEAD") {
+			return ErrorResponse(405, "method_not_allowed",
+				"only GET on /status");
+		}
+		return HandleStatus(req);
+	}
+
+	if (path == "/api/v0/downloads") {
+		if (req.method == "GET" || req.method == "HEAD") {
+			return HandleDownloads(req);
+		}
+		if (req.method == "POST") {
+			// add a download by ed2k link.
+			return HandleDownloadAdd(req);
+		}
+		return ErrorResponse(405, "method_not_allowed",
+			"only GET / HEAD / POST on /downloads");
+	}
+
+	// bulk clear-completed.
+	if (path == "/api/v0/downloads/clear_completed") {
+		if (req.method != "POST") {
+			return ErrorResponse(405, "method_not_allowed",
+				"only POST on /downloads/clear_completed");
+		}
+		return HandleDownloadsClearCompleted(req);
+	}
+
+	// /uploads was retired in — /clients covers the full
+	// peer surface (every upload_state, including queue waiters and
+	// download peers); consumers filter client-side by upload_state.
+	if (path == "/api/v0/clients") {
+		if (req.method != "GET" && req.method != "HEAD") {
+			return ErrorResponse(405, "method_not_allowed",
+				"only GET on /clients");
+		}
+		return HandleClients(req);
+	}
+
+	if (path == "/api/v0/shared") {
+		if (req.method != "GET" && req.method != "HEAD") {
+			return ErrorResponse(405, "method_not_allowed",
+				"only GET on /shared");
+		}
+		return HandleSharedList(req);
+	}
+
+	if (path == "/api/v0/shared/reload") {
+		if (req.method != "POST") {
+			return ErrorResponse(405, "method_not_allowed",
+				"only POST on /shared/reload");
+		}
+		return HandleSharedReload(req);
+	}
+
+	if (path == "/api/v0/servers") {
+		if (req.method == "GET" || req.method == "HEAD") {
+			return HandleServers(req);
+		}
+		if (req.method == "POST") {
+			// add a server by host:port.
+			return HandleServerAdd(req);
+		}
+		return ErrorResponse(405, "method_not_allowed",
+			"only GET / HEAD / POST on /servers");
+	}
+
+	if (path == "/api/v0/servers/update") {
+		if (req.method != "POST") {
+			return ErrorResponse(405, "method_not_allowed",
+				"only POST on /servers/update");
+		}
+		return HandleServerUpdateFromUrl(req);
+	}
+
+	// server connect & remove (single server by ECID).
+	// Address-keyed aliases live in the same block — same handlers,
+	// different lookup path. ECID forms are tried first because they
+	// match a single-segment pattern that's cheaper to dispatch; the
+	// address forms have a colon in the capture which the path pattern
+	// captures as a single segment too.
+	{
+		static const auto server_connect =
+			web_api_path::ParsePattern("/api/v0/servers/{ecid}/connect");
+		static const auto server_one =
+			web_api_path::ParsePattern("/api/v0/servers/{ecid}");
+		const auto path_segs = web_api_path::SplitPath(path);
+		std::map<std::string, std::string> caps;
+		if (web_api_path::Match(server_connect, path_segs, caps)) {
+			if (req.method != "POST") {
+				return ErrorResponse(405, "method_not_allowed",
+					"only POST on /servers/{ecid}/connect");
+			}
+			// `{ecid}` capture also matches "<ip>:<port>" because the
+			// path-pattern matcher is opaque-segment. Disambiguate
+			// here: if the capture contains a colon, treat it as an
+			// address-keyed alias.
+			if (caps["ecid"].find(':') != std::string::npos) {
+				return HandleServerConnectByAddress(req, caps["ecid"]);
+			}
+			return HandleServerConnect(req, caps["ecid"]);
+		}
+		if (web_api_path::Match(server_one, path_segs, caps)) {
+			if (req.method != "DELETE") {
+				return ErrorResponse(405, "method_not_allowed",
+					"only DELETE on /servers/{ecid}");
+			}
+			if (caps["ecid"].find(':') != std::string::npos) {
+				return HandleServerDeleteByAddress(req, caps["ecid"]);
+			}
+			return HandleServerDelete(req, caps["ecid"]);
+		}
+	}
+
+	if (path == "/api/v0/kad") {
+		if (req.method != "GET" && req.method != "HEAD") {
+			return ErrorResponse(405, "method_not_allowed",
+				"only GET on /kad");
+		}
+		return HandleKad(req);
+	}
+
+	// connection control.
+	if (path == "/api/v0/networks/connect") {
+		if (req.method != "POST") {
+			return ErrorResponse(405, "method_not_allowed",
+				"only POST on /networks/connect");
+		}
+		return HandleNetworksConnect(req);
+	}
+	if (path == "/api/v0/networks/disconnect") {
+		if (req.method != "POST") {
+			return ErrorResponse(405, "method_not_allowed",
+				"only POST on /networks/disconnect");
+		}
+		return HandleNetworksDisconnect(req);
+	}
+	// /api/v0/kad/connect and /api/v0/kad/disconnect were dropped in
+	// favour of /networks/{connect,disconnect} with `{"network":"kad"}`
+	// — the two were strict aliases and the granular-selector form on
+	// /networks/* makes the dedicated shortcut redundant.
+	if (path == "/api/v0/kad/bootstrap") {
+		if (req.method != "POST") {
+			return ErrorResponse(405, "method_not_allowed",
+				"only POST on /kad/bootstrap");
+		}
+		return HandleKadBootstrap(req);
+	}
+
+	// shared file priority PATCH. `{hash}` is the lowercase 32-char hex
+	// MD4 hash.
+	{
+		static const auto shared_detail =
+			web_api_path::ParsePattern("/api/v0/shared/{hash}");
+		const auto path_segs = web_api_path::SplitPath(path);
+		std::map<std::string, std::string> caps;
+		if (web_api_path::Match(shared_detail, path_segs, caps)) {
+			if (req.method != "PATCH") {
+				return ErrorResponse(405, "method_not_allowed",
+					"only PATCH on /shared/{hash}");
+			}
+			return HandleSharedPatch(req, caps["hash"]);
+		}
+	}
+
+	if (path == "/api/v0/categories") {
+		if (req.method == "GET" || req.method == "HEAD") {
+			return HandleCategories(req);
+		}
+		if (req.method == "POST") {
+			return HandleCategoryCreate(req);
+		}
+		return ErrorResponse(405, "method_not_allowed",
+			"only GET / HEAD / POST on /categories");
+	}
+
+	// single-category PATCH/DELETE.
+	{
+		static const auto category_one =
+			web_api_path::ParsePattern("/api/v0/categories/{index}");
+		const auto path_segs = web_api_path::SplitPath(path);
+		std::map<std::string, std::string> caps;
+		if (web_api_path::Match(category_one, path_segs, caps)) {
+			if (req.method == "PATCH") {
+				return HandleCategoryUpdate(req, caps["index"]);
+			}
+			if (req.method == "DELETE") {
+				return HandleCategoryDelete(req, caps["index"]);
+			}
+			return ErrorResponse(405, "method_not_allowed",
+				"only PATCH / DELETE on /categories/{index}");
+		}
+	}
+
+	if (path == "/api/v0/preferences") {
+		if (req.method == "GET" || req.method == "HEAD") {
+			return HandlePreferences(req);
+		}
+		if (req.method == "PATCH") {
+			return HandlePreferencesPatch(req);
+		}
+		return ErrorResponse(405, "method_not_allowed",
+			"only GET / HEAD / PATCH on /preferences");
+	}
+
+	if (path == "/api/v0/logs/amule") {
+		if (req.method == "GET" || req.method == "HEAD") {
+			return HandleLogAmule(req);
+		}
+		if (req.method == "DELETE") {
+			return HandleLogAmuleReset(req);
+		}
+		return ErrorResponse(405, "method_not_allowed",
+			"only GET / HEAD / DELETE on /logs/amule");
+	}
+
+	if (path == "/api/v0/logs/serverinfo") {
+		if (req.method == "GET" || req.method == "HEAD") {
+			return HandleLogServerinfo(req);
+		}
+		if (req.method == "DELETE") {
+			return HandleLogServerinfoReset(req);
+		}
+		return ErrorResponse(405, "method_not_allowed",
+			"only GET / HEAD / DELETE on /logs/serverinfo");
+	}
+
+	if (path == "/api/v0/stats/tree") {
+		if (req.method != "GET" && req.method != "HEAD") {
+			return ErrorResponse(405, "method_not_allowed",
+				"only GET on /stats/tree");
+		}
+		return HandleStatsTree(req);
+	}
+
+	// search.
+	if (path == "/api/v0/search") {
+		if (req.method != "POST") {
+			return ErrorResponse(405, "method_not_allowed",
+				"only POST on /search (use GET /search/results for results)");
+		}
+		return HandleSearchStart(req);
+	}
+	if (path == "/api/v0/search/stop") {
+		if (req.method != "POST") {
+			return ErrorResponse(405, "method_not_allowed",
+				"only POST on /search/stop");
+		}
+		return HandleSearchStop(req);
+	}
+	if (path == "/api/v0/search/results") {
+		if (req.method != "GET" && req.method != "HEAD") {
+			return ErrorResponse(405, "method_not_allowed",
+				"only GET on /search/results");
+		}
+		return HandleSearchResults(req);
+	}
+	{
+		static const auto search_download =
+			web_api_path::ParsePattern("/api/v0/search/results/{hash}/download");
+		const auto path_segs = web_api_path::SplitPath(path);
+		std::map<std::string, std::string> caps;
+		if (web_api_path::Match(search_download, path_segs, caps)) {
+			if (req.method != "POST") {
+				return ErrorResponse(405, "method_not_allowed",
+					"only POST on /search/results/{hash}/download");
+			}
+			return HandleSearchDownload(req, caps["hash"]);
+		}
+	}
+
+	// /stats/graphs/{graph} — path-pattern matches the four allowed
+	// graph names ("download" / "upload" / "connections" / "kad").
+	{
+		static const auto graph_pattern =
+			web_api_path::ParsePattern("/api/v0/stats/graphs/{graph}");
+		const auto segs = web_api_path::SplitPath(path);
+		std::map<std::string, std::string> caps;
+		if (web_api_path::Match(graph_pattern, segs, caps)) {
+			if (req.method != "GET" && req.method != "HEAD") {
+				return ErrorResponse(405, "method_not_allowed",
+					"only GET on /stats/graphs/{graph}");
+			}
+			return HandleStatsGraph(req, caps["graph"]);
+		}
+	}
+
+	// /downloads/{hash} — single-resource detail (GET / HEAD) and the
+	// mutation surface (PATCH for status/priority/category, DELETE for
+	// clear-completed single). `{hash}` is the lowercase 32-char hex
+	// MD4 hash (dispatcher lower-cases input on the way in).
+	{
+		static const auto download_detail =
+			web_api_path::ParsePattern("/api/v0/downloads/{hash}");
+		const auto path_segs = web_api_path::SplitPath(path);
+		std::map<std::string, std::string> caps;
+		if (web_api_path::Match(download_detail, path_segs, caps)) {
+			if (req.method == "GET" || req.method == "HEAD") {
+				return HandleDownloadDetail(req, caps["hash"]);
+			}
+			if (req.method == "PATCH") {
+				return HandleDownloadPatch(req, caps["hash"]);
+			}
+			if (req.method == "DELETE") {
+				return HandleDownloadDelete(req, caps["hash"]);
+			}
+			return ErrorResponse(405, "method_not_allowed",
+				"only GET / HEAD / PATCH / DELETE on /downloads/{hash}");
+		}
+	}
+
+	// Static-frontend fallthrough. Anything that didn't match an
+	// /api/v0/* route and is a safe-method request for a non-API path
+	// is a candidate. ServeStaticFile is a no-op (404) when StaticRoot
+	// is unset, so API-only deployments keep their historical
+	// behaviour. Auth is intentionally NOT required here — the shell
+	// itself is public; the API calls it makes still go through the
+	// per-handler role gates.
+	if ((req.method == "GET" || req.method == "HEAD")
+	    && path.compare(0, 5, "/api/") != 0) {
+		return ServeStaticFile(req, path);
+	}
+
+	return ErrorResponse(404, "not_found", "no such endpoint");
+}
+
+
+CHttpServer::Response CApiDispatcher::ServeStaticFile(
+	const CHttpServer::Request &req,
+	const std::string          &url_path)
+{
+	// Resolve once per process. Conf override wins; otherwise we walk
+	// the install-path discovery chain. `m_static_root_resolved`
+	// guards against re-walking on every request (the answer is
+	// stable for the daemon's lifetime — operators editing
+	// amuleapi.conf at runtime restart the daemon).
+	if (!m_static_root_resolved) {
+		m_static_root_cache  = m_config.ServerCfg().static_root;
+		if (m_static_root_cache.empty()) {
+			m_static_root_cache = ResolveDefaultStaticDir();
+		}
+		m_static_root_resolved = true;
+	}
+	const std::string &root = m_static_root_cache;
+	if (root.empty()) {
+		// API-only deployment AND nothing on disk to fall back to.
+		return ErrorResponse(404, "not_found", "no such endpoint");
+	}
+
+	// Map "/" → SPA entry. Strip leading slash so the join is relative;
+	// `LooksMalicious` (run at the top of DispatchToHandler) already
+	// rejected NUL / encoded NUL / encoded `..` / literal `..` segments.
+	std::string rel = (url_path == "/" || url_path.empty())
+		? std::string("index.html")
+		: url_path.substr(1);
+
+	std::string fs_path;
+	struct stat st{};
+	std::string body;
+	bool found = webapi::ResolveWithinRoot(root, rel, fs_path)
+	          && ReadStaticFile(fs_path, body, st);
+
+	// SPA fallback: an extension-less path that didn't resolve is
+	// treated as a client-side route and served the entry document so
+	// a deep-linked reload still boots the app. Paths that look like
+	// an asset (carry an extension) 404 honestly so a missing JS/CSS
+	// failure is visible rather than masked by an HTML response.
+	if (!found && rel.find('.') == std::string::npos) {
+		if (webapi::ResolveWithinRoot(root, "index.html", fs_path)
+		 && ReadStaticFile(fs_path, body, st)) {
+			rel = "index.html";
+			found = true;
+		}
+	}
+
+	if (!found) {
+		return ErrorResponse(404, "not_found", "no such file");
+	}
+
+	const std::string etag = BuildStaticEtag(st);
+
+	// Conditional GET: client sent If-None-Match → 304 with no body
+	// when the ETag matches. ETag is mtime+size, so a rebuild of the
+	// frontend invalidates without manual cache-busting.
+	auto inm = req.headers.find("If-None-Match");
+	if (inm != req.headers.end() && inm->second == etag) {
+		CHttpServer::Response r;
+		r.status = 304;
+		r.headers["ETag"] = etag;
+		return r;
+	}
+
+	CHttpServer::Response r;
+	r.status       = 200;
+	r.content_type = StaticContentType(rel);
+	r.body         = (req.method == "HEAD") ? std::string() : std::move(body);
+	r.headers["ETag"] = etag;
+	return r;
+}
+
+
+CHttpServer::Response CApiDispatcher::HandleVersion(const CHttpServer::Request &)
+{
+	CHttpServer::Response r;
+	r.status       = 200;
+	r.content_type = "application/json";
+	CJsonWriter w;
+	w.BeginObject();
+	  w.Key("name");          w.ValueString(wxT("amuleapi"));
+	  w.Key("api_version");   w.ValueString(wxT("v0"));
+	  w.Key("amule_version"); w.ValueString(wxString::FromAscii(VERSION));
+	w.EndObject();
+	const wxString js = w.GetBuffer();
+	const wxScopedCharBuffer ub = js.utf8_str();
+	r.body.assign(ub.data(), ub.length());
+	return r;
+}
+
+
+CHttpServer::Response CApiDispatcher::HandleLogin(const CHttpServer::Request &req)
+{
+	const std::string &ip = req.remote_addr;
+
+	// Rate-limit BEFORE we touch the credential path. A locked-out
+	// IP burns no MD5 cycles and can't drive a side-channel that
+	// would distinguish "lockout in effect" from "wrong password".
+	const auto decision = m_rateLimiter.Check(ip);
+	if (decision.locked_out) {
+		CHttpServer::Response r = ErrorResponse(429, "rate_limited",
+			"too many failed attempts; retry later");
+		char retry_after[32];
+		std::snprintf(retry_after, sizeof(retry_after), "%lld",
+			static_cast<long long>(decision.retry_after_seconds));
+		r.headers["Retry-After"] = retry_after;
+		return r;
+	}
+
+	// Refuse early if amuleapi has no passwords configured at all —
+	// otherwise every login would silently fail and the operator
+	// debugging "why isn't login working" would think the JWT was
+	// the problem.
+	if (m_config.AdminPasswordMd5().empty()
+	    && m_config.GuestPasswordMd5().empty()) {
+		return ErrorResponse(503, "login_disabled",
+			"amuleapi has no admin/guest password configured; "
+			"set one via `amuleapi --set-admin-pass=<plain>`");
+	}
+
+	// Parse `{"password": "<plain>"}`. Anything else gets a 400.
+	// Route through ParseJsonObjectBody so the pre-auth login path
+	// shares the same depth-cap defence the rest of the body
+	// parses get; without it a deeply-nested `{"a":{"a":...}}` would
+	// blow the worker thread's stack via picojson's recursive
+	// descent — and login is reachable unauthenticated.
+	picojson::value v;
+	std::string err;
+	if (!ParseJsonObjectBody(req.body, v, err)) {
+		return ErrorResponse(400, "bad_request",
+			"body must be JSON object {\"password\": \"...\"}");
+	}
+	const auto &obj = v.get<picojson::object>();
+	auto pw_it = obj.find("password");
+	if (pw_it == obj.end() || !pw_it->second.is<std::string>()) {
+		return ErrorResponse(400, "bad_request",
+			"missing or non-string `password` field");
+	}
+	const wxString plain = wxString::FromUTF8(
+		pw_it->second.get<std::string>().c_str());
+	const std::string md5_hex(
+		MD5Sum(plain).GetHash().utf8_str());
+
+	// Compare against admin first, then guest. ConstantTimeEquals is
+	// length-leaking by design (both sides are 32 hex chars, so length
+	// is fixed) but byte-content equality is constant time.
+	Role role = Role::GUEST;
+	bool match = false;
+	if (!m_config.AdminPasswordMd5().empty()
+	    && webcommon::ConstantTimeEquals(md5_hex, m_config.AdminPasswordMd5())) {
+		role  = Role::ADMIN;
+		match = true;
+	} else if (!m_config.GuestPasswordMd5().empty()
+	           && webcommon::ConstantTimeEquals(md5_hex, m_config.GuestPasswordMd5())) {
+		role  = Role::GUEST;
+		match = true;
+	}
+
+	if (!match) {
+		m_rateLimiter.NoteFailure(ip);
+		return ErrorResponse(401, "invalid_credentials",
+			"password does not match any configured role");
+	}
+
+	m_rateLimiter.NoteSuccess(ip);
+
+	const CJwt::IssuedToken issued = m_jwt.Issue(role);
+
+	CHttpServer::Response r;
+	r.status       = 200;
+	r.content_type = "application/json";
+	r.headers["Set-Cookie"] = MakeSetCookie(
+		kSessionCookieName, issued.token, issued.expires_at);
+
+	// Default (cookie-auth, browser): the HttpOnly+SameSite cookie
+	// carries the token. Echoing it into the JSON body would defeat
+	// HttpOnly — any XSS that `fetch('/auth/login', ...)` could read
+	// the body and exfiltrate the bearer. So the default response is
+	// deliberately token-less.
+	//
+	// Bearer opt-in (SDK / curl / no cookie jar): client passes
+	// `Accept: application/jwt` or `?type=bearer` to get the bearer
+	// shape — `token`, `expires_at`, `expires_at_unix`, `jti`. The
+	// cookie still ships; bearer clients can ignore it.
+	bool wants_bearer = false;
+	{
+		const std::string accept = FindHeaderCaseInsensitive(
+			req.headers, "Accept");
+		if (accept.find("application/jwt") != std::string::npos) {
+			wants_bearer = true;
+		}
+		if (!wants_bearer) {
+			std::string q;
+			const std::size_t qpos = req.target.find('?');
+			if (qpos != std::string::npos) q = req.target.substr(qpos + 1);
+			const auto qmap = web_api_path::ParseQuery(q);
+			const auto it = qmap.find("type");
+			if (it != qmap.end() && it->second == "bearer") {
+				wants_bearer = true;
+			}
+		}
+	}
+
+	CJsonWriter w;
+	w.BeginObject();
+	  if (wants_bearer) {
+	    w.Key("token");           w.ValueString(wxString::FromUTF8(issued.token.c_str()));
+	  }
+	  w.Key("role");
+	  w.ValueString(role == Role::ADMIN ? wxT("admin") : wxT("guest"));
+	  w.Key("expires_at");      w.ValueString(wxString::FromUTF8(
+	                              webapi::FormatIso8601Utc(issued.expires_at).c_str()));
+	  w.Key("expires_at_unix"); w.ValueInt(static_cast<int64_t>(issued.expires_at));
+	  if (wants_bearer) {
+	    w.Key("jti");           w.ValueString(wxString::FromUTF8(issued.jti.c_str()));
+	  }
+	w.EndObject();
+	const wxString js = w.GetBuffer();
+	const wxScopedCharBuffer ub = js.utf8_str();
+	r.body.assign(ub.data(), ub.length());
+	return r;
+}
+
+
+CHttpServer::Response CApiDispatcher::HandleLogout(const CHttpServer::Request &req)
+{
+	// Generic-401 cap applies to logout too — repeat 401s here are a
+	// credential-stuffing signal even on the idempotent path. Locked-
+	// out IPs short-circuit before any MAC compare.
+	const std::string &ip = req.remote_addr;
+	{
+		const auto decision = m_authRateLimiter.Check(ip);
+		if (decision.locked_out) {
+			CHttpServer::Response r = ErrorResponse(429, "rate_limited",
+				"too many failed auth attempts; retry later");
+			char retry_after[32];
+			std::snprintf(retry_after, sizeof(retry_after), "%lld",
+				static_cast<long long>(decision.retry_after_seconds));
+			r.headers["Retry-After"] = retry_after;
+			return r;
+		}
+	}
+
+	// Logout is idempotent. A revoked-but-not-yet-expired token
+	// should still get a 200 noop — the operation it requested has
+	// already happened. Without this, a browser tab that does
+	// `fetch('/auth/logout', ...)` twice in quick succession (page
+	// reload during the request, double-tap on the menu, etc.) sees
+	// a 401 on the second attempt and renders a confusing "session
+	// expired" toast. Inline a softer flow than AuthenticateRequest:
+	// reject only on bad-sig/expired/missing, treat revoked as a
+	// noop.
+	std::string token;
+	auto auth_it = req.headers.find("Authorization");
+	if (auth_it == req.headers.end()) {
+		for (const auto &h : req.headers) {
+			if (h.first.size() == 13
+			    && strncasecmp(h.first.c_str(), "Authorization", 13) == 0) {
+				auth_it = req.headers.find(h.first);
+				break;
+			}
+		}
+	}
+	if (auth_it != req.headers.end()) {
+		token = webapi::ExtractBearerToken(auth_it->second);
+	}
+	if (token.empty()) {
+		auto ck_it = req.headers.find("Cookie");
+		if (ck_it == req.headers.end()) {
+			for (const auto &h : req.headers) {
+				if (h.first.size() == 6
+				    && strncasecmp(h.first.c_str(), "Cookie", 6) == 0) {
+					ck_it = req.headers.find(h.first);
+					break;
+				}
+			}
+		}
+		if (ck_it != req.headers.end()) {
+			token = webapi::ExtractCookieValue(ck_it->second, kSessionCookieName);
+		}
+	}
+	if (token.empty()) {
+		m_authRateLimiter.NoteFailure(ip);
+		return ErrorResponse(401, "unauthorized",
+			"missing bearer token or session cookie");
+	}
+	CJwt::VerifyResult v;
+	if (!m_jwt.Verify(token, v)) {
+		m_authRateLimiter.NoteFailure(ip);
+		return ErrorResponse(401, "unauthorized",
+			"invalid or expired token");
+	}
+	// Already revoked → 200 noop (don't re-revoke, don't re-emit a
+	// clear-cookie that might race with the browser's own delete).
+	if (!m_revocations.IsRevoked(v.jti)) {
+		// Add the jti to the revocation set with the JWT's own exp as
+		// the TTL — once the token would have expired anyway, the GC
+		// drops the entry.
+		m_revocations.Revoke(v.jti, v.exp);
+	}
+	m_authRateLimiter.NoteSuccess(ip);
+
+	CHttpServer::Response r;
+	r.status       = 200;
+	r.content_type = "application/json";
+	r.headers["Set-Cookie"] = MakeClearCookie(kSessionCookieName);
+
+	CJsonWriter w;
+	w.BeginObject();
+	  w.Key("ok"); w.ValueBool(true);
+	w.EndObject();
+	const wxString js = w.GetBuffer();
+	const wxScopedCharBuffer ub = js.utf8_str();
+	r.body.assign(ub.data(), ub.length());
+	return r;
+}
+
+
+CHttpServer::Response CApiDispatcher::HandleSession(const CHttpServer::Request &req)
+{
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations, m_authRateLimiter,
+		kSessionCookieName);
+	if (!a.ok) return a.rejection;
+
+	CHttpServer::Response r;
+	r.status       = 200;
+	r.content_type = "application/json";
+
+	CJsonWriter w;
+	w.BeginObject();
+	  w.Key("role");
+	  w.ValueString(a.verified.role == Role::ADMIN ? wxT("admin") : wxT("guest"));
+	  w.Key("jti"); w.ValueString(wxString::FromUTF8(a.verified.jti.c_str()));
+	  w.Key("exp");      w.ValueString(wxString::FromUTF8(
+	                       webapi::FormatIso8601Utc(a.verified.exp).c_str()));
+	  w.Key("exp_unix"); w.ValueInt(static_cast<int64_t>(a.verified.exp));
+	w.EndObject();
+	const wxString js = w.GetBuffer();
+	const wxScopedCharBuffer ub = js.utf8_str();
+	r.body.assign(ub.data(), ub.length());
+	return r;
+}
+
+
+CHttpServer::Response CApiDispatcher::HandleStatus(const CHttpServer::Request &req)
+{
+	// Read endpoints: any authenticated role is enough (admin OR
+	// guest). mutating endpoints will gate on `admin` only.
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations, m_authRateLimiter,
+		kSessionCookieName);
+	if (!a.ok) return a.rejection;
+
+	// Until the refresher has completed at least one tick, the cache
+	// is empty. Return 503 with a structured code so clients can
+	// retry rather than guessing — saves a round of confused log-
+	// reading when the daemon just came up.
+	if (!m_state.HasFirstSnapshot()) {
+		return ErrorResponse(503, "ec_unavailable",
+			"amuleapi has not received its first EC snapshot yet");
+	}
+
+	// Single shared_lock for the whole composite read. Dashboard()
+	// returns a (status, kad, snapshot_at, ec_connected) tuple in
+	// one m_state lock acquisition, so a refresher tick cannot land
+	// between sub-snapshots and produce an inconsistent rollup
+	// (kad.network from tick N+1 while ed2k.* / speeds.* are from
+	// tick N). Caller-side aliases keep the rest of the function
+	// reading the same way the four-accessor version did.
+	const webapi::CState::DashboardSnapshot d = m_state.Dashboard();
+	const webapi::StatusSnapshot &s   = d.status;
+	const webapi::KadSnapshot    &k   = d.kad;
+	const std::time_t            ts  = d.snapshot_at;
+	const bool                   ec  = d.ec_connected;
+
+	CHttpServer::Response r;
+	r.status       = 200;
+	r.content_type = "application/json";
+
+	CJsonWriter w;
+	w.BeginObject();
+	  // snapshot_at + snapshot_at_unix were retired from
+	  // every envelope response so the ETag/If-None-Match cache
+	  // actually gets cache hits on list endpoints.
+	  // `ec_connected` is the dedicated staleness signal — it flips
+	  // false when the refresher tick fails. Standard HTTP `Date:`
+	  // header carries wall-clock for any consumer that needs it.
+	  w.Key("ec_connected");     w.ValueBool(ec);
+	  (void) ts;
+
+	  w.Key("ed2k");
+	  w.BeginObject();
+	    w.Key("state");       w.ValueString(wxString::FromUTF8(s.ed2k_state.c_str()));
+	    w.Key("low_id");      w.ValueBool(s.ed2k_lowid);
+	    w.Key("server_name"); w.ValueString(wxString::FromUTF8(s.server_name.c_str()));
+	    w.Key("server_ip");   w.ValueString(wxString::FromUTF8(s.server_ip.c_str()));
+	    w.Key("server_port"); w.ValueInt(static_cast<int64_t>(s.server_port));
+	  w.EndObject();
+
+	  w.Key("kad");
+	  w.BeginObject();
+	    w.Key("state");      w.ValueString(wxString::FromUTF8(s.kad_state.c_str()));
+	    w.Key("firewalled"); w.ValueBool(s.kad_firewalled);
+	    // Network rollup — same numbers GET /kad serves under
+	    // `network.{users,files,nodes}`. Surfaced here so /status
+	    // is a one-call dashboard view (matches the RFC contract
+	    // §4.1 `kad.network: {users, files}`; we ship `nodes` too
+	    // because it costs nothing extra and the desktop GUI shows
+	    // it in the same place). `k` was snapshotted at the top of
+	    // the handler in the same shared_lock batch as `s`, so
+	    // these counters describe the same refresher tick as
+	    // ed2k.* / speeds.* above.
+	    w.Key("network");
+	    w.BeginObject();
+	      w.Key("users"); w.ValueInt(static_cast<int64_t>(k.users));
+	      w.Key("files"); w.ValueInt(static_cast<int64_t>(k.files));
+	      w.Key("nodes"); w.ValueInt(static_cast<int64_t>(k.nodes));
+	    w.EndObject();
+	  w.EndObject();
+
+	  w.Key("speeds");
+	  w.BeginObject();
+	    w.Key("download_bps"); w.ValueInt(static_cast<int64_t>(s.download_bps));
+	    w.Key("upload_bps");   w.ValueInt(static_cast<int64_t>(s.upload_bps));
+	  w.EndObject();
+
+	  w.Key("queue");
+	  w.BeginObject();
+	    w.Key("upload_queue_length"); w.ValueInt(static_cast<int64_t>(s.ul_queue_len));
+	    w.Key("total_source_count");  w.ValueInt(static_cast<int64_t>(s.total_src_count));
+	  w.EndObject();
+	  // Nickname is a /preferences field, not a /status one.
+	w.EndObject();
+
+	const wxString js = w.GetBuffer();
+	const wxScopedCharBuffer ub = js.utf8_str();
+	r.body.assign(ub.data(), ub.length());
+	return r;
+}
+
+
+namespace {
+
+// Compact helper — every read endpoint serialises its body the same
+// way (build a wxString via CJsonWriter, then utf8_str into the
+// response body). Hide the boilerplate behind a helper that takes a
+// ready CJsonWriter.
+void FinalizeJsonBody(CJsonWriter &w, CHttpServer::Response &r)
+{
+	const wxString js = w.GetBuffer();
+	const wxScopedCharBuffer ub = js.utf8_str();
+	r.body.assign(ub.data(), ub.length());
+}
+
+
+// Write a single download object. Used both inline (in the list
+// endpoint, iterated) and as the body of the detail endpoint (bare,
+// per Q3). The `include_envelope_keys` flag controls whether we
+// emit the snapshot_at envelope around it — list mode wraps in its
+// own envelope, detail mode is the bare object.
+// PARTSIZE — the byte width of a single partfile chunk in amule
+// (9.28 MB). Authoritative copy is in `protocol/ed2k/Constants.h`;
+// duplicated here to avoid pulling that header into Api.cpp (which
+// would cascade into the protocol-level types). amule has never
+// changed PARTSIZE since the ed2k spec was frozen.
+constexpr std::uint64_t kPartSize = 9728000ull;
+
+
+// Render the per-part state array from the decoded gap list +
+// per-part source counts. Algorithm cribbed from the reference REST
+// branch's `EmitProgressParts` (WebServerApi.cpp:897-952):
+//  - count = ceil(size / PARTSIZE)
+//  - mark a part "has gap" if any byte-range in `gaps` covers it
+//  - state = "complete"   (no gap) /
+//            "incomplete" (gap + sources > 0) /
+//            "missing"    (gap + zero sources)
+// `gaps` is flat (start, end) uint64 pairs. Both inclusive on amule's
+// side (CGapList::Encode semantics).
+void WriteProgressParts(CJsonWriter &w, const webapi::FileSnapshot &f)
+{
+	w.Key("parts");
+	w.BeginArray();
+	if (f.size == 0) { w.EndArray(); return; }
+	const std::uint64_t part_count = (f.size + kPartSize - 1) / kPartSize;
+	std::vector<bool> has_gap(part_count, false);
+	const auto &gaps = f.download.decoded_gaps;
+	const std::size_t gap_pair_count = gaps.size() / 2;
+	for (std::size_t g = 0; g < gap_pair_count; ++g) {
+		const std::uint64_t gap_start = gaps[2 * g];
+		const std::uint64_t gap_end   = gaps[2 * g + 1];
+		const std::uint64_t start_idx = gap_start / kPartSize;
+		const std::uint64_t end_idx   = gap_end   / kPartSize;
+		for (std::uint64_t i = start_idx;
+		     i <= end_idx && i < part_count; ++i) {
+			has_gap[static_cast<std::size_t>(i)] = true;
+		}
+	}
+	const auto &part_sources = f.download.decoded_part_sources;
+	for (std::uint64_t i = 0; i < part_count; ++i) {
+		const std::uint16_t sources =
+			(static_cast<std::size_t>(i) < part_sources.size())
+			? part_sources[static_cast<std::size_t>(i)]
+			: static_cast<std::uint16_t>(0);
+		const char *state =
+			!has_gap[static_cast<std::size_t>(i)] ? "complete" :
+			(sources > 0 ? "incomplete" : "missing");
+		w.BeginObject();
+		  w.Key("state");   w.ValueString(wxString::FromAscii(state));
+		  w.Key("sources"); w.ValueInt(static_cast<int64_t>(sources));
+		w.EndObject();
+	}
+	w.EndArray();
+}
+
+
+void WriteDownloadObject(CJsonWriter &w, const webapi::FileSnapshot &f,
+                         bool include_parts = false)
+{
+	w.BeginObject();
+	  w.Key("hash");            w.ValueString(wxString::FromUTF8(f.hash.c_str()));
+	  w.Key("name");            w.ValueString(wxString::FromUTF8(f.name.c_str()));
+	  w.Key("ed2k_link");       w.ValueString(wxString::FromUTF8(f.ed2k_link.c_str()));
+	  w.Key("size");            w.ValueInt(static_cast<int64_t>(f.size));
+	  w.Key("size_done");       w.ValueInt(static_cast<int64_t>(f.download.size_done));
+	  w.Key("size_xfer");       w.ValueInt(static_cast<int64_t>(f.download.size_xfer));
+	  w.Key("speed_bps");       w.ValueInt(static_cast<int64_t>(f.download.speed_bps));
+	  w.Key("status");          w.ValueString(wxString::FromUTF8(f.download.status.c_str()));
+	  w.Key("priority");        w.ValueString(wxString::FromUTF8(f.priority.c_str()));
+	  w.Key("priority_auto");   w.ValueBool(f.download.priority_auto);
+	  w.Key("category");        w.ValueInt(static_cast<int64_t>(f.download.category));
+	  w.Key("sources");
+	  w.BeginObject();
+	    w.Key("total");        w.ValueInt(static_cast<int64_t>(f.download.sources_total));
+	    w.Key("not_current");  w.ValueInt(static_cast<int64_t>(f.download.sources_not_current));
+	    w.Key("transferring"); w.ValueInt(static_cast<int64_t>(f.download.sources_transferring));
+	    w.Key("a4af");         w.ValueInt(static_cast<int64_t>(f.download.sources_a4af));
+	  w.EndObject();
+	  w.Key("progress");
+	  w.BeginObject();
+	    w.Key("percent"); w.ValueDouble(f.download.percent);
+	    if (include_parts) {
+	      WriteProgressParts(w, f);
+	    }
+	  w.EndObject();
+	w.EndObject();
+}
+
+
+void WriteClientObject(CJsonWriter &w, const webapi::ClientSnapshot &c)
+{
+	w.BeginObject();
+	  w.Key("client_ecid");           w.ValueInt(static_cast<int64_t>(c.ecid));
+	  w.Key("client_name");           w.ValueString(wxString::FromUTF8(c.client_name.c_str()));
+	  w.Key("user_hash");             w.ValueString(wxString::FromUTF8(c.user_hash.c_str()));
+	  w.Key("ip");                    w.ValueString(wxString::FromUTF8(c.ip.c_str()));
+	  w.Key("port");                  w.ValueInt(static_cast<int64_t>(c.port));
+	  w.Key("software");              w.ValueString(wxString::FromUTF8(c.software.c_str()));
+	  w.Key("software_version");      w.ValueString(wxString::FromUTF8(c.software_version.c_str()));
+	  w.Key("os_info");               w.ValueString(wxString::FromUTF8(c.os_info.c_str()));
+	  w.Key("upload_state");          w.ValueString(wxString::FromUTF8(c.upload_state.c_str()));
+	  w.Key("download_state");        w.ValueString(wxString::FromUTF8(c.download_state.c_str()));
+	  w.Key("ident_state");           w.ValueString(wxString::FromUTF8(c.ident_state.c_str()));
+	  w.Key("download_file_name");   w.ValueString(wxString::FromUTF8(c.download_file_name.c_str()));
+	  w.Key("upload_file_hash");   w.ValueString(wxString::FromUTF8(c.upload_file_hash.c_str()));
+	  w.Key("download_file_hash"); w.ValueString(wxString::FromUTF8(c.download_file_hash.c_str()));
+	  w.Key("xfer");
+	  w.BeginObject();
+	    w.Key("up_session");     w.ValueInt(static_cast<int64_t>(c.xfer_up_session));
+	    w.Key("down_session");   w.ValueInt(static_cast<int64_t>(c.xfer_down_session));
+	    w.Key("up_total");       w.ValueInt(static_cast<int64_t>(c.xfer_up_total));
+	    w.Key("down_total");     w.ValueInt(static_cast<int64_t>(c.xfer_down_total));
+	  w.EndObject();
+	  w.Key("upload_speed_bps");      w.ValueInt(static_cast<int64_t>(c.upload_speed_bps));
+	  w.Key("download_speed_bps");    w.ValueInt(static_cast<int64_t>(c.download_speed_bps));
+	  w.Key("queue_waiting_position"); w.ValueInt(static_cast<int64_t>(c.queue_waiting_position));
+	  w.Key("remote_queue_rank");     w.ValueInt(static_cast<int64_t>(c.remote_queue_rank));
+	  w.Key("score");                 w.ValueInt(static_cast<int64_t>(c.score));
+	  w.Key("obfuscation_status");    w.ValueString(wxString::FromUTF8(c.obfuscation_status.c_str()));
+	  w.Key("friend_slot");           w.ValueBool(c.friend_slot);
+	w.EndObject();
+}
+
+
+void WriteSharedObject(CJsonWriter &w, const webapi::FileSnapshot &f)
+{
+	w.BeginObject();
+	  w.Key("hash");              w.ValueString(wxString::FromUTF8(f.hash.c_str()));
+	  w.Key("name");              w.ValueString(wxString::FromUTF8(f.name.c_str()));
+	  w.Key("ed2k_link");         w.ValueString(wxString::FromUTF8(f.ed2k_link.c_str()));
+	  w.Key("size");              w.ValueInt(static_cast<int64_t>(f.size));
+	  w.Key("priority");          w.ValueString(wxString::FromUTF8(f.priority.c_str()));
+	  w.Key("complete_sources");  w.ValueInt(static_cast<int64_t>(f.shared.complete_sources));
+	  w.Key("xfer");
+	  w.BeginObject();
+	    w.Key("session"); w.ValueInt(static_cast<int64_t>(f.shared.xfer_session));
+	    w.Key("total");   w.ValueInt(static_cast<int64_t>(f.shared.xfer_total));
+	  w.EndObject();
+	  w.Key("requests");
+	  w.BeginObject();
+	    w.Key("session"); w.ValueInt(static_cast<int64_t>(f.shared.requests_session));
+	    w.Key("total");   w.ValueInt(static_cast<int64_t>(f.shared.requests_total));
+	  w.EndObject();
+	  w.Key("accepts");
+	  w.BeginObject();
+	    w.Key("session"); w.ValueInt(static_cast<int64_t>(f.shared.accepts_session));
+	    w.Key("total");   w.ValueInt(static_cast<int64_t>(f.shared.accepts_total));
+	  w.EndObject();
+	w.EndObject();
+}
+
+
+// Helper for every list endpoint's envelope: snapshot_at +
+// snapshot_at_unix + the list under its named key. ec_unavailable +
+// 503 is also emitted here so each handler doesn't repeat the check.
+template <class T, class WriterFn>
+CHttpServer::Response ListResponse(const webapi::CState &state,
+                                   const char           *plural_key,
+                                   const std::vector<T> &items,
+                                   WriterFn              write_item)
+{
+	if (!state.HasFirstSnapshot()) {
+		return ErrorResponse(503, "ec_unavailable",
+			"amuleapi has not received its first EC snapshot yet");
+	}
+	CHttpServer::Response r;
+	r.status       = 200;
+	r.content_type = "application/json";
+	// envelope responses dropped snapshot_at_* — they were
+	// defeating the ETag cache by churning the body bytes
+	// every refresher tick. The ETag is now the cache
+	// validator; HTTP `Date:` is the wall-clock.
+	CJsonWriter w;
+	w.BeginObject();
+	  w.Key(plural_key);
+	  w.BeginArray();
+	  for (const auto &item : items) write_item(w, item);
+	  w.EndArray();
+	w.EndObject();
+	FinalizeJsonBody(w, r);
+	return r;
+}
+
+}  // namespace
+
+
+// ===================================================================
+// Mutation helpers — shared by every Handle{Resource}{Patch,Add,
+// Delete} below. Every mutation handler follows:
+//  1. AuthenticateRequest (bearer or cookie)
+//  2. RequireAdmin (mutations are admin-only)
+//  3. Parse JSON body
+//  4. Send EC mutation packet via SendRecvSerialized
+//  5. EC_OP_NOOP = success; EC_OP_FAILED carries amuled's rejection
+//  6. Run RefresherTick inline on the HTTP thread so the response
+//     sees post-mutation state (vs. next refresher tick ~1 s later)
+//  7. Return the updated resource (or 201 / 204 per HTTP convention)
+// ===================================================================
+
+namespace {
+
+// Admin role gate. Drop-in for the standard ` if (!a.ok) return
+// a.rejection;` pattern; mutations chain ` if (auto r = RequireAdmin(a))
+// return *r;` immediately after.
+std::unique_ptr<CHttpServer::Response> RequireAdmin(const AuthOutcome &a)
+{
+	if (a.verified.role != Role::ADMIN) {
+		return std::unique_ptr<CHttpServer::Response>(
+			new CHttpServer::Response(
+				ErrorResponse(403, "forbidden",
+					"admin role required for this endpoint")));
+	}
+	return nullptr;
+}
+
+
+// JSON body parser. Returns true on success; false + `err` on
+// failure. Non-object roots are rejected.
+//
+// Pre-parse depth cap. picojson uses unbounded recursive descent for
+// `_parse_array` / `_parse_object` — a `{"a":{"a":...}}` body deep
+// enough blows the worker thread stack. 32 openers is past anything
+// legitimate (bodies are flat lists of scalars). Mirrors CJwt::Verify.
+bool ParseJsonObjectBody(const std::string &body, picojson::value &out,
+                         std::string &err)
+{
+	constexpr std::size_t kMaxJsonOpeners = 32;
+	std::size_t openers = 0;
+	for (char c : body) {
+		if (c == '{' || c == '[') {
+			if (++openers > kMaxJsonOpeners) {
+				err = "JSON nesting too deep";
+				return false;
+			}
+		}
+	}
+	const std::string parse_err = picojson::parse(out, body);
+	if (!parse_err.empty()) {
+		err = "malformed JSON: " + parse_err;
+		return false;
+	}
+	if (!out.is<picojson::object>()) {
+		err = "request body must be a JSON object";
+		return false;
+	}
+	return true;
+}
+
+
+// Surfaces the EC_OP_FAILED reply shape from amuled. The standard
+// amuled failure response carries one or more EC_TAG_STRING children
+// with the rejection message; we relay the first one to the client.
+// Returns true if the response was an error (caller short-circuits);
+// false on EC_OP_NOOP or any other "success" shape.
+bool IsEcFailedResponse(const CECPacket *resp, std::string &out_msg)
+{
+	if (!resp) return false;
+	if (resp->GetOpCode() != EC_OP_FAILED) return false;
+	out_msg = "amuled rejected the operation";
+	for (CECPacket::const_iterator it = resp->begin(); it != resp->end(); ++it) {
+		const CECTag *t = &*it;
+		if (t->GetTagName() == EC_TAG_STRING) {
+			out_msg = std::string(t->GetStringData().utf8_str());
+			break;
+		}
+	}
+	return true;
+}
+
+
+// Map our wire-string priorities back to amule's PR_* encoding (the
+// inverse of DownloadPriorityName in Refresher.cpp). Note: amule's
+// PR_* values for DOWNLOADS only span LOW/NORMAL/HIGH/VERYHIGH/AUTO —
+// no `very_low` (that's a shared/upload-side enum). `release` is the
+// wire string for the highest priority (`PR_VERYHIGH`, raw code 3).
+// `PR_AUTO=5` is the magic value amule's PartFile uses internally
+// when the user picks "auto".
+// Returns false if the wire string isn't a known download priority.
+bool DownloadPriorityToCode(const std::string &name, std::uint8_t &out)
+{
+	if      (name == "low")      { out = PR_LOW;      return true; }
+	else if (name == "normal")   { out = PR_NORMAL;   return true; }
+	else if (name == "high")     { out = PR_HIGH;     return true; }
+	else if (name == "release")  { out = PR_VERYHIGH; return true; }
+	else if (name == "auto")     { out = PR_AUTO;     return true; }
+	return false;
+}
+
+
+// MD4 hex string → CMD4Hash. Returns false if the string isn't 32
+// lowercase-or-uppercase hex chars (we tolerate both cases; the
+// route already lowercases what comes off the URL).
+bool HashFromHex(const std::string &hex, CMD4Hash &out)
+{
+	if (hex.size() != 32) return false;
+	return out.Decode(wxString::FromAscii(hex.c_str()));
+}
+
+}  // namespace
+
+
+CHttpServer::Response CApiDispatcher::HandleDownloads(const CHttpServer::Request &req)
+{
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations, m_authRateLimiter,
+		kSessionCookieName);
+	if (!a.ok) return a.rejection;
+
+	// /downloads filters status=="completed" out by default.
+	// amuled holds finished downloads in `m_completedDownloads` as a
+	// separate "awaiting clear" list; surfacing them in /downloads
+	// alongside in-progress files confuses consumers reading
+	// "what's currently in the transfer queue." Opt back in with
+	// `?include_completed=1`. The detail endpoint
+	// `GET /downloads/{hash}` is unaffected — consumer asked for that
+	// specific file. may add an explicit clear-completed
+	// mutation.
+	bool include_completed = false;
+	{
+		std::string query;
+		const std::size_t q = req.target.find('?');
+		if (q != std::string::npos) query = req.target.substr(q + 1);
+		const auto qmap = web_api_path::ParseQuery(query);
+		const auto it = qmap.find("include_completed");
+		if (it != qmap.end()) {
+			const std::string &v = it->second;
+			include_completed = (v == "1" || v == "true" || v == "yes");
+		}
+	}
+
+	std::vector<webapi::FileSnapshot> downloads = m_state.Downloads();
+	if (!include_completed) {
+		downloads.erase(
+			std::remove_if(downloads.begin(), downloads.end(),
+				[](const webapi::FileSnapshot &d) {
+					return d.download.status == "completed";
+				}),
+			downloads.end());
+	}
+
+	return ListResponse(m_state, "downloads", downloads,
+		[](CJsonWriter &w, const webapi::FileSnapshot &d) {
+			// List mode — omit `progress.parts` (Q2 + the per-list
+			// shape: omitting parts keeps the list response compact,
+			// detail endpoint is where parts ship).
+			WriteDownloadObject(w, d, /*include_parts=*/false);
+		});
+}
+
+
+CHttpServer::Response CApiDispatcher::HandleClients(const CHttpServer::Request &req)
+{
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations, m_authRateLimiter,
+		kSessionCookieName);
+	if (!a.ok) return a.rejection;
+
+	// Optional `?filter=uploads | downloads | active` query parameter.
+	// `uploads`   → peers actively transferring TO us (upload_state ==
+	//              "uploading"). Subset that maps to the legacy
+	//              amuleweb "Uploads" page.
+	// `downloads` → peers we're actively pulling FROM (download_state
+	//              == "downloading").
+	// `active`    → union of the two; everything currently moving
+	//              bytes either direction.
+	// No filter → every peer the daemon knows about (default, v0.1
+	// shape).
+	std::string filter;
+	{
+		std::string query;
+		const std::size_t q = req.target.find('?');
+		if (q != std::string::npos) query = req.target.substr(q + 1);
+		const auto qmap = web_api_path::ParseQuery(query);
+		const auto it = qmap.find("filter");
+		if (it != qmap.end()) filter = it->second;
+	}
+	if (!filter.empty() && filter != "uploads" && filter != "downloads"
+	    && filter != "active") {
+		return ErrorResponse(400, "bad_request",
+			"`filter` must be one of \"uploads\", \"downloads\", \"active\"");
+	}
+
+	auto clients = m_state.Clients();
+	if (!filter.empty()) {
+		auto matches = [&](const webapi::ClientSnapshot &c) {
+			const bool up   = (c.upload_state   == "uploading");
+			const bool down = (c.download_state == "downloading");
+			if (filter == "uploads")   return up;
+			if (filter == "downloads") return down;
+			/* active */               return up || down;
+		};
+		clients.erase(
+			std::remove_if(clients.begin(), clients.end(),
+				[&](const webapi::ClientSnapshot &c) { return !matches(c); }),
+			clients.end());
+	}
+
+	return ListResponse(m_state, "clients", clients, WriteClientObject);
+}
+
+
+CHttpServer::Response CApiDispatcher::HandleSharedList(const CHttpServer::Request &req)
+{
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations, m_authRateLimiter,
+		kSessionCookieName);
+	if (!a.ok) return a.rejection;
+	return ListResponse(m_state, "shared", m_state.Shared(),
+		WriteSharedObject);
+}
+
+
+CHttpServer::Response CApiDispatcher::HandleDownloadDetail(
+	const CHttpServer::Request &req,
+	const std::string          &key)
+{
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations, m_authRateLimiter,
+		kSessionCookieName);
+	if (!a.ok) return a.rejection;
+
+	if (!m_state.HasFirstSnapshot()) {
+		return ErrorResponse(503, "ec_unavailable",
+			"amuleapi has not received its first EC snapshot yet");
+	}
+
+	// {hash} is the 32-char lowercase-hex MD4. URL is case-tolerant;
+	// State writes lowercase, so we down-case the capture before the
+	// O(1) m_hash_to_ecid lookup.
+	webapi::FileSnapshot d;
+	std::string needle = key;
+	std::transform(needle.begin(), needle.end(), needle.begin(),
+		[](unsigned char c) { return std::tolower(c); });
+	if (!m_state.FindDownload(needle, d)) {
+		return ErrorResponse(404, "not_found",
+			"no download with that hash");
+	}
+
+	// Bare object per Q3: list endpoint envelopes, detail endpoint
+	// is the resource itself. No `snapshot_at` here — clients that
+	// need freshness metadata can read the list endpoint.
+	//
+	// `include_parts=true` adds `progress.parts: [...]` to the
+	// response. List endpoint omits this — `parts` can be 100K+
+	// entries for a multi-TiB download (Q2: no cap), which clients
+	// don't need to walk through when paging the queue overview.
+	CHttpServer::Response r;
+	r.status       = 200;
+	r.content_type = "application/json";
+	CJsonWriter w;
+	WriteDownloadObject(w, d, /*include_parts=*/true);
+	FinalizeJsonBody(w, r);
+	return r;
+}
+
+
+
+CHttpServer::Response CApiDispatcher::HandleDownloadAdd(
+	const CHttpServer::Request &req)
+{
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations, m_authRateLimiter,
+		kSessionCookieName);
+	if (!a.ok) return a.rejection;
+	if (auto rej = RequireAdmin(a)) return *rej;
+
+	// Body shape (two forms — both accepted, exactly one required):
+	//  {"ed2k_link": "ed2k://|file|...|/", "category": 0}    — singular
+	//  {"links": ["ed2k://|file|...|/", ...], "category": 0} — array
+	// `links` is the RFC §4.2 shape (PR #132); `ed2k_link` ships for
+	// backwards compatibility with the v0.1.0 wire. Mixing both is a
+	// 400.
+	picojson::value root;
+	std::string parse_err;
+	if (!ParseJsonObjectBody(req.body, root, parse_err)) {
+		return ErrorResponse(400, "bad_request", parse_err.c_str());
+	}
+	const auto &obj = root.get<picojson::object>();
+
+	std::vector<std::string> links;
+	{
+		const auto it_single = obj.find("ed2k_link");
+		const auto it_array  = obj.find("links");
+		if (it_single != obj.end() && it_array != obj.end()) {
+			return ErrorResponse(400, "bad_request",
+				"send either `ed2k_link` (single) or `links` (array), "
+				"not both");
+		}
+		if (it_single != obj.end()) {
+			if (!it_single->second.is<std::string>()) {
+				return ErrorResponse(400, "bad_request",
+					"`ed2k_link` must be a string");
+			}
+			links.push_back(it_single->second.get<std::string>());
+		} else if (it_array != obj.end()) {
+			if (!it_array->second.is<picojson::array>()) {
+				return ErrorResponse(400, "bad_request",
+					"`links` must be an array of ed2k://strings");
+			}
+			const auto &arr = it_array->second.get<picojson::array>();
+			if (arr.empty()) {
+				return ErrorResponse(400, "bad_request",
+					"`links` must contain at least one entry");
+			}
+			links.reserve(arr.size());
+			for (const auto &v : arr) {
+				if (!v.is<std::string>()) {
+					return ErrorResponse(400, "bad_request",
+						"every entry in `links` must be a string");
+				}
+				links.push_back(v.get<std::string>());
+			}
+		} else {
+			return ErrorResponse(400, "bad_request",
+				"required field missing: send `ed2k_link` (string) or "
+				"`links` (array of strings)");
+		}
+		for (const auto &link : links) {
+			if (link.size() < 7 || link.compare(0, 7, "ed2k://") != 0) {
+				return ErrorResponse(400, "bad_request",
+					"every link must start with ed2k://");
+			}
+		}
+	}
+	std::uint8_t category = 0;
+	{
+		const auto it = obj.find("category");
+		if (it != obj.end()) {
+			if (!it->second.is<double>()) {
+				return ErrorResponse(400, "bad_request",
+					"`category` must be a non-negative integer");
+			}
+			const double v = it->second.get<double>();
+			if (v < 0 || v > 255) {
+				return ErrorResponse(400, "bad_request",
+					"`category` must be in [0, 255]");
+			}
+			category = static_cast<std::uint8_t>(v);
+		}
+	}
+
+	// Build one EC_OP_ADD_LINK packet per link. amuled's add-link op
+	// is single-link-only on the wire; we batch at the HTTP layer so
+	// clients only pay one round-trip. We accumulate accepted /
+	// failed / disconnected-mid-batch into separate lists and report
+	// the whole picture at the end — never short-circuit on an EC
+	// blip mid-batch (an unconditional 503 would silently throw away
+	// the links amuled already queued from earlier iterations).
+	std::vector<std::string> accepted_links;
+	std::vector<std::string> failed_links;
+	std::vector<std::string> ec_disconnected_links;
+	std::string first_error;
+	for (const auto &link : links) {
+		std::unique_ptr<CECPacket> ec_req(new CECPacket(EC_OP_ADD_LINK));
+		CECTag link_tag(EC_TAG_STRING, wxString::FromUTF8(link.c_str()));
+		link_tag.AddTag(CECTag(EC_TAG_PARTFILE_CAT, category));
+		ec_req->AddTag(link_tag);
+		const CECPacket *ec_resp = m_app.SendRecvSerialized(ec_req.get());
+		if (!ec_resp) {
+			ec_disconnected_links.push_back(link);
+			if (first_error.empty()) {
+				first_error = "EC roundtrip failed for ADD_LINK";
+			}
+			continue;
+		}
+		std::string ec_err_msg;
+		const bool failed = IsEcFailedResponse(ec_resp, ec_err_msg);
+		delete ec_resp;
+		if (failed) {
+			failed_links.push_back(link);
+			if (first_error.empty()) first_error = ec_err_msg;
+		} else {
+			accepted_links.push_back(link);
+		}
+	}
+
+	// Inline-refresh the cache so the response sees post-mutation
+	// state. amuled's ADD_LINK is asynchronous (the partfile gets
+	// allocated + hashed before it shows up in m_filelist), so the
+	// new entry may not surface until the *next* tick — we'd still
+	// return 202 Accepted with an empty resource. For now: refresh,
+	// then return {ok: true} and leave the GET /downloads to surface
+	// the new entry.
+	(void) RefresherTick(m_app, m_state);
+
+	CHttpServer::Response r;
+	// 202 (all clean), 207 (any rejection or mid-batch disconnect
+	// with at least one accept), 503 (every link blocked by an EC
+	// disconnect — the operator's amuled is unreachable and nothing
+	// could land at all). 207 is per the partial-success convention
+	// documented in QUICKSTART.
+	const bool all_ok = failed_links.empty()
+	                    && ec_disconnected_links.empty();
+	const bool none_landed = accepted_links.empty();
+	r.status = all_ok ? 202
+	         : (none_landed && !ec_disconnected_links.empty())
+	             ? 503
+	             : 207;
+	r.content_type = "application/json";
+	CJsonWriter w;
+	w.BeginObject();
+	  w.Key("ok");        w.ValueBool(all_ok);
+	  w.Key("accepted");  w.ValueInt(static_cast<int64_t>(accepted_links.size()));
+	  w.Key("failed");    w.ValueInt(static_cast<int64_t>(failed_links.size()));
+	  w.Key("disconnected"); w.ValueInt(
+	      static_cast<int64_t>(ec_disconnected_links.size()));
+	  if (!accepted_links.empty()) {
+	      w.Key("accepted_links");
+	      w.BeginArray();
+	      for (const auto &l : accepted_links) {
+	          w.ValueString(wxString::FromUTF8(l.c_str()));
+	      }
+	      w.EndArray();
+	  }
+	  if (!failed_links.empty()) {
+	      w.Key("failed_links");
+	      w.BeginArray();
+	      for (const auto &l : failed_links) {
+	          w.ValueString(wxString::FromUTF8(l.c_str()));
+	      }
+	      w.EndArray();
+	  }
+	  if (!ec_disconnected_links.empty()) {
+	      // Distinct from `failed_links` — amuled didn't reject these,
+	      // it just wasn't there to receive them. Clients can retry
+	      // this subset once /api/v0/status reports ec_connected=true.
+	      w.Key("disconnected_links");
+	      w.BeginArray();
+	      for (const auto &l : ec_disconnected_links) {
+	          w.ValueString(wxString::FromUTF8(l.c_str()));
+	      }
+	      w.EndArray();
+	  }
+	  if (!first_error.empty()) {
+	      w.Key("first_error");
+	      w.ValueString(wxString::FromUTF8(first_error.c_str()));
+	  }
+	  w.Key("message");
+	  w.ValueString(wxString::FromUTF8(
+		"link(s) accepted; new downloads will appear after amuled has "
+		"allocated and hashed the partfiles (typically within one "
+		"refresher tick)"));
+	w.EndObject();
+	FinalizeJsonBody(w, r);
+	return r;
+}
+
+
+CHttpServer::Response CApiDispatcher::HandleDownloadPatch(
+	const CHttpServer::Request &req, const std::string &key)
+{
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations, m_authRateLimiter,
+		kSessionCookieName);
+	if (!a.ok) return a.rejection;
+	if (auto rej = RequireAdmin(a)) return *rej;
+
+	if (!m_state.HasFirstSnapshot()) {
+		return ErrorResponse(503, "ec_unavailable",
+			"amuleapi has not received its first EC snapshot yet");
+	}
+
+	webapi::FileSnapshot d;
+	std::string needle = key;
+	std::transform(needle.begin(), needle.end(), needle.begin(),
+		[](unsigned char c) { return std::tolower(c); });
+	if (!m_state.FindDownload(needle, d)) {
+		return ErrorResponse(404, "not_found", "no download with that hash");
+	}
+
+	picojson::value root;
+	std::string parse_err;
+	if (!ParseJsonObjectBody(req.body, root, parse_err)) {
+		return ErrorResponse(400, "bad_request", parse_err.c_str());
+	}
+	const auto &obj = root.get<picojson::object>();
+
+	// Downstream EC ops still address by MD4 hash — read it back off
+	// the snapshot we just resolved.
+	CMD4Hash file_hash;
+	if (!HashFromHex(d.hash, file_hash)) {
+		return ErrorResponse(500, "internal_error",
+			"failed to decode partfile hash");
+	}
+
+	// Each field present in the body fires one EC mutation. We
+	// process them in a fixed order (status, priority, category) so
+	// the wire effect is deterministic regardless of JSON key order.
+	auto send_op = [&](ec_opcode_t op,
+	                   bool has_inner, ec_tagname_t inner_name,
+	                   std::uint8_t inner_value) -> CHttpServer::Response {
+		std::unique_ptr<CECPacket> p(new CECPacket(op));
+		CECTag hash_tag(EC_TAG_PARTFILE, file_hash);
+		if (has_inner) {
+			hash_tag.AddTag(CECTag(inner_name, inner_value));
+		}
+		p->AddTag(hash_tag);
+		const CECPacket *r = m_app.SendRecvSerialized(p.get());
+		if (!r) {
+			return ErrorResponse(503, "ec_unavailable",
+				"EC roundtrip failed");
+		}
+		std::string ec_err_msg;
+		if (IsEcFailedResponse(r, ec_err_msg)) {
+			delete r;
+			return ErrorResponse(400, "amuled_rejected", ec_err_msg.c_str());
+		}
+		delete r;
+		CHttpServer::Response ok;
+		ok.status = 200;
+		return ok;
+	};
+
+	bool any_change = false;
+
+	// status: "paused" | "resumed"
+	{
+		const auto it = obj.find("status");
+		if (it != obj.end()) {
+			if (!it->second.is<std::string>()) {
+				return ErrorResponse(400, "bad_request",
+					"`status` must be one of \"paused\" or \"resumed\"");
+			}
+			const std::string &v = it->second.get<std::string>();
+			ec_opcode_t op;
+			if      (v == "paused")  op = EC_OP_PARTFILE_PAUSE;
+			else if (v == "resumed") op = EC_OP_PARTFILE_RESUME;
+			else {
+				return ErrorResponse(400, "bad_request",
+					"`status` must be one of \"paused\" or \"resumed\"");
+			}
+			auto err = send_op(op, /*has_inner=*/false,
+				static_cast<ec_tagname_t>(0), 0);
+			if (err.status >= 400) return err;
+			any_change = true;
+		}
+	}
+
+	// priority: "very_low"|"low"|"normal"|"high"|"release"|"auto"
+	{
+		const auto it = obj.find("priority");
+		if (it != obj.end()) {
+			if (!it->second.is<std::string>()) {
+				return ErrorResponse(400, "bad_request",
+					"`priority` must be a wire-string enum");
+			}
+			std::uint8_t code = 0;
+			if (!DownloadPriorityToCode(it->second.get<std::string>(), code)) {
+				return ErrorResponse(400, "bad_request",
+					"`priority` must be one of "
+					"low, normal, high, release, auto");
+			}
+			auto err = send_op(EC_OP_PARTFILE_PRIO_SET, /*has_inner=*/true,
+				EC_TAG_PARTFILE_PRIO, code);
+			if (err.status >= 400) return err;
+			any_change = true;
+		}
+	}
+
+	// category: integer
+	{
+		const auto it = obj.find("category");
+		if (it != obj.end()) {
+			if (!it->second.is<double>()) {
+				return ErrorResponse(400, "bad_request",
+					"`category` must be a non-negative integer");
+			}
+			const double v = it->second.get<double>();
+			if (v < 0 || v > 255) {
+				return ErrorResponse(400, "bad_request",
+					"`category` must be in [0, 255]");
+			}
+			auto err = send_op(EC_OP_PARTFILE_SET_CAT, /*has_inner=*/true,
+				EC_TAG_PARTFILE_CAT, static_cast<std::uint8_t>(v));
+			if (err.status >= 400) return err;
+			any_change = true;
+		}
+	}
+
+	if (!any_change) {
+		return ErrorResponse(400, "bad_request",
+			"request body must include at least one of "
+			"`status`, `priority`, or `category`");
+	}
+
+	// Inline refresh so the response below sees post-mutation state.
+	(void) RefresherTick(m_app, m_state);
+
+	// Re-read the snapshot — fall back to the prior copy if the
+	// cache evicted it between mutations and this read (vanishingly
+	// rare; would mean amuled removed it between our SendRecv and
+	// the refresh).
+	webapi::FileSnapshot d_after;
+	if (!m_state.FindDownload(d.hash, d_after)) d_after = d;
+
+	CHttpServer::Response r;
+	r.status       = 200;
+	r.content_type = "application/json";
+	CJsonWriter w;
+	WriteDownloadObject(w, d_after, /*include_parts=*/false);
+	FinalizeJsonBody(w, r);
+	return r;
+}
+
+
+
+CHttpServer::Response CApiDispatcher::HandleDownloadDelete(
+	const CHttpServer::Request &req, const std::string &key)
+{
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations, m_authRateLimiter,
+		kSessionCookieName);
+	if (!a.ok) return a.rejection;
+	if (auto rej = RequireAdmin(a)) return *rej;
+
+	if (!m_state.HasFirstSnapshot()) {
+		return ErrorResponse(503, "ec_unavailable",
+			"amuleapi has not received its first EC snapshot yet");
+	}
+
+	webapi::FileSnapshot d;
+	std::string needle = key;
+	std::transform(needle.begin(), needle.end(), needle.begin(),
+		[](unsigned char c) { return std::tolower(c); });
+	if (!m_state.FindDownload(needle, d)) {
+		return ErrorResponse(404, "not_found", "no download with that hash");
+	}
+
+	// DELETE only handles ACTIVE downloads (anything not "completed").
+	// Completed entries live in amuled's m_completedDownloads
+	// staging list, and the only EC op that touches that list is
+	// EC_OP_CLEAR_COMPLETED — which doesn't delete the on-disk file
+	// from Incoming, it just acks the post-completion notification.
+	// Conflating the two under one verb confused operators who
+	// reasonably expected DELETE to remove a file from disk. Route
+	// the completed case through POST /downloads/clear_completed
+	// (which accepts an optional {hash} body for per-entry clears)
+	// so the verb-vs-disk-semantic mapping stays unambiguous.
+	if (d.download.status == "completed") {
+		return ErrorResponse(409, "completed_use_clear_completed",
+			"DELETE only removes active downloads (deletes .part/.met "
+			"files from disk). Use POST /downloads/clear_completed "
+			"with optional {\"hash\":\"...\"} body to clear a completed "
+			"entry's post-completion notification — the file in the "
+			"Incoming directory is NEVER removed via this API.");
+	}
+
+	CMD4Hash file_hash;
+	if (!HashFromHex(d.hash, file_hash)) {
+		return ErrorResponse(500, "internal_error",
+			"failed to decode partfile hash");
+	}
+	std::unique_ptr<CECPacket> ec_req(new CECPacket(EC_OP_PARTFILE_DELETE));
+	ec_req->AddTag(CECTag(EC_TAG_PARTFILE, file_hash));
+
+	const CECPacket *ec_resp = m_app.SendRecvSerialized(ec_req.get());
+	if (!ec_resp) {
+		return ErrorResponse(503, "ec_unavailable",
+			"EC roundtrip failed for DELETE");
+	}
+	std::string ec_err_msg;
+	if (IsEcFailedResponse(ec_resp, ec_err_msg)) {
+		delete ec_resp;
+		return ErrorResponse(400, "amuled_rejected", ec_err_msg.c_str());
+	}
+	delete ec_resp;
+
+	// Inline refresh — the next GET /downloads must not show the
+	// deleted entry. The cache eviction happens via FILE_REMOVED in
+	// the GET_UPDATE response.
+	(void) RefresherTick(m_app, m_state);
+
+	CHttpServer::Response r;
+	r.status       = 200;
+	r.content_type = "application/json";
+	CJsonWriter w;
+	w.BeginObject();
+	  w.Key("ok"); w.ValueBool(true);
+	  w.Key("hash"); w.ValueString(wxString::FromUTF8(d.hash.c_str()));
+	w.EndObject();
+	FinalizeJsonBody(w, r);
+	return r;
+}
+
+
+CHttpServer::Response CApiDispatcher::HandleDownloadsClearCompleted(
+	const CHttpServer::Request &req)
+{
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations, m_authRateLimiter,
+		kSessionCookieName);
+	if (!a.ok) return a.rejection;
+	if (auto rej = RequireAdmin(a)) return *rej;
+
+	if (!m_state.HasFirstSnapshot()) {
+		return ErrorResponse(503, "ec_unavailable",
+			"amuleapi has not received its first EC snapshot yet");
+	}
+
+	// Two shapes share this endpoint:
+	//  * no body (or all-whitespace body) → bulk clear every
+	//    completed entry. Original shape.
+	//  * `{"hash": "<md4hex>"}` → clear that single completed entry.
+	//    Hash must currently match a download with status=="completed";
+	//    active / unknown hashes return 404.
+	// The response envelope is identical in both branches so a client
+	// that wraps the call doesn't need to fork on its own input.
+	std::string target_hash;
+	bool body_has_content = false;
+	for (char c : req.body) {
+		if (c != ' ' && c != '\t' && c != '\n' && c != '\r') {
+			body_has_content = true;
+			break;
+		}
+	}
+	if (body_has_content) {
+		picojson::value root;
+		std::string parse_err;
+		if (!ParseJsonObjectBody(req.body, root, parse_err)) {
+			return ErrorResponse(400, "bad_request", parse_err.c_str());
+		}
+		const auto &obj = root.get<picojson::object>();
+		const auto it_hash = obj.find("hash");
+		if (it_hash != obj.end()) {
+			if (!it_hash->second.is<std::string>()) {
+				return ErrorResponse(400, "bad_request",
+					"`hash` must be a string");
+			}
+			target_hash = it_hash->second.get<std::string>();
+			std::transform(target_hash.begin(), target_hash.end(),
+				target_hash.begin(),
+				[](unsigned char c) { return std::tolower(c); });
+		}
+		// Future-proof: silently ignore unknown keys rather than 400
+		// so adding a flag later (e.g. {"hash": "...", "force": true})
+		// doesn't break old clients.
+	}
+
+	// Collect target ECID(s). For the by-hash form, only one entry;
+	// for the bulk form, every cached download with status=="completed".
+	std::vector<std::uint32_t> ecids;
+	std::vector<std::string>   hashes_cleared;
+	if (!target_hash.empty()) {
+		webapi::FileSnapshot d;
+		if (!m_state.FindDownload(target_hash, d)) {
+			return ErrorResponse(404, "not_found",
+				"no download with that hash");
+		}
+		if (d.download.status != "completed") {
+			return ErrorResponse(409, "not_completed",
+				"target download exists but is not in the completed "
+				"staging list (status != \"completed\"). To remove an "
+				"active partfile, use DELETE /downloads/{hash}.");
+		}
+		ecids.push_back(d.ecid);
+		hashes_cleared.push_back(d.hash);
+	} else {
+		for (const auto &d : m_state.Downloads()) {
+			if (d.download.status == "completed") {
+				ecids.push_back(d.ecid);
+				hashes_cleared.push_back(d.hash);
+			}
+		}
+	}
+
+	if (ecids.empty()) {
+		// Nothing to do — return 200 with cleared:0 so consumers can
+		// distinguish "no-op" from "amuled rejected" (both end up
+		// with no visible change).
+		CHttpServer::Response r;
+		r.status       = 200;
+		r.content_type = "application/json";
+		CJsonWriter w;
+		w.BeginObject();
+		  w.Key("ok");      w.ValueBool(true);
+		  w.Key("cleared"); w.ValueInt(0);
+		w.EndObject();
+		FinalizeJsonBody(w, r);
+		return r;
+	}
+
+	// One EC roundtrip with all ECIDs (per amulegui's pattern at
+	// amule-remote-gui.cpp:2238-2246).
+	std::unique_ptr<CECPacket> ec_req(new CECPacket(EC_OP_CLEAR_COMPLETED));
+	for (std::uint32_t ecid : ecids) {
+		ec_req->AddTag(CECTag(EC_TAG_ECID, ecid));
+	}
+	const CECPacket *ec_resp = m_app.SendRecvSerialized(ec_req.get());
+	if (!ec_resp) {
+		return ErrorResponse(503, "ec_unavailable",
+			"EC roundtrip failed for CLEAR_COMPLETED");
+	}
+	std::string ec_err_msg;
+	if (IsEcFailedResponse(ec_resp, ec_err_msg)) {
+		delete ec_resp;
+		return ErrorResponse(400, "amuled_rejected", ec_err_msg.c_str());
+	}
+	delete ec_resp;
+
+	// Inline refresh — the response below + the next GET both must
+	// show the post-clear state.
+	(void) RefresherTick(m_app, m_state);
+
+	CHttpServer::Response r;
+	r.status       = 200;
+	r.content_type = "application/json";
+	CJsonWriter w;
+	w.BeginObject();
+	  w.Key("ok");           w.ValueBool(true);
+	  w.Key("cleared");      w.ValueInt(static_cast<int64_t>(ecids.size()));
+	  w.Key("cleared_hashes");
+	  w.BeginArray();
+	  for (const auto &h : hashes_cleared) {
+	    w.ValueString(wxString::FromUTF8(h.c_str()));
+	  }
+	  w.EndArray();
+	w.EndObject();
+	FinalizeJsonBody(w, r);
+	return r;
+}
+
+
+// --- /servers, /kad, /categories, /preferences -------------------------
+
+namespace {
+
+void WriteServerObject(CJsonWriter &w, const webapi::ServerSnapshot &s)
+{
+	w.BeginObject();
+	  // `ecid` is the URL key for /servers/{ecid}/connect and
+	  // /servers/{ecid}. intentionally surfaced
+	  // it on /clients for the same reason; servers got it later.
+	  w.Key("ecid");        w.ValueInt(static_cast<int64_t>(s.ecid));
+	  w.Key("name");        w.ValueString(wxString::FromUTF8(s.name.c_str()));
+	  w.Key("description"); w.ValueString(wxString::FromUTF8(s.description.c_str()));
+	  w.Key("version");     w.ValueString(wxString::FromUTF8(s.version.c_str()));
+	  w.Key("address");     w.ValueString(wxString::FromUTF8(s.address.c_str()));
+	  w.Key("port");        w.ValueInt(static_cast<int64_t>(s.port));
+	  w.Key("users");       w.ValueInt(static_cast<int64_t>(s.users));
+	  w.Key("max_users");   w.ValueInt(static_cast<int64_t>(s.max_users));
+	  w.Key("files");       w.ValueInt(static_cast<int64_t>(s.files));
+	  w.Key("priority");    w.ValueString(wxString::FromUTF8(s.priority.c_str()));
+	  w.Key("ping_ms");     w.ValueInt(static_cast<int64_t>(s.ping_ms));
+	  w.Key("failed");      w.ValueInt(static_cast<int64_t>(s.failed));
+	  w.Key("static");      w.ValueBool(s.is_static);
+	w.EndObject();
+}
+
+
+void WriteCategoryObject(CJsonWriter &w, const webapi::CategorySnapshot &c)
+{
+	w.BeginObject();
+	  w.Key("index");    w.ValueInt(static_cast<int64_t>(c.index));
+	  w.Key("name");     w.ValueString(wxString::FromUTF8(c.name.c_str()));
+	  w.Key("path");     w.ValueString(wxString::FromUTF8(c.path.c_str()));
+	  w.Key("comment");  w.ValueString(wxString::FromUTF8(c.comment.c_str()));
+	  w.Key("color");    w.ValueInt(static_cast<int64_t>(c.color));
+	  w.Key("priority"); w.ValueString(wxString::FromUTF8(c.priority.c_str()));
+	w.EndObject();
+}
+
+}  // namespace
+
+
+CHttpServer::Response CApiDispatcher::HandleServers(const CHttpServer::Request &req)
+{
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations, m_authRateLimiter,
+		kSessionCookieName);
+	if (!a.ok) return a.rejection;
+	return ListResponse(m_state, "servers", m_state.Servers(),
+		WriteServerObject);
+}
+
+
+
+namespace {
+
+// Parse an integer ECID from a path capture. Returns false on
+// negative, overflow, or non-digit content (the API expects positive
+// 32-bit ECIDs from the URL).
+bool ParseEcidPath(const std::string &s, std::uint32_t &out)
+{
+	if (s.empty()) return false;
+	char *end = nullptr;
+	// strtoull (not strtoul) because `unsigned long` is 32-bit on
+	// Windows — there the `v > 0xFFFFFFFFu` overflow guard below
+	// would be a tautology and an out-of-range path-segment like
+	// `99999999999` would saturate to ULONG_MAX = 0xFFFFFFFF, then
+	// silently match an actual ECID 0xFFFFFFFF. strtoull is 64-bit
+	// everywhere so the cap is meaningful regardless of platform.
+	errno = 0;
+	const unsigned long long v = std::strtoull(s.c_str(), &end, 10);
+	if (end == s.c_str() || *end != '\0') return false;
+	if (errno == ERANGE) return false;
+	if (v > 0xFFFFFFFFull) return false;
+	out = static_cast<std::uint32_t>(v);
+	return true;
+}
+
+
+// Look up a server in the State cache by ECID. Returns false if
+// no match — the handler then 404s.
+bool FindServerByEcid(const webapi::CState &state, std::uint32_t ecid,
+                      webapi::ServerSnapshot &out)
+{
+	const auto all = state.Servers();
+	for (const auto &s : all) {
+		if (s.ecid == ecid) { out = s; return true; }
+	}
+	return false;
+}
+
+}  // namespace
+
+
+CHttpServer::Response CApiDispatcher::HandleServerAdd(
+	const CHttpServer::Request &req)
+{
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations, m_authRateLimiter,
+		kSessionCookieName);
+	if (!a.ok) return a.rejection;
+	if (auto rej = RequireAdmin(a)) return *rej;
+
+	picojson::value root;
+	std::string parse_err;
+	if (!ParseJsonObjectBody(req.body, root, parse_err)) {
+		return ErrorResponse(400, "bad_request", parse_err.c_str());
+	}
+	const auto &obj = root.get<picojson::object>();
+
+	std::string address;
+	{
+		const auto it = obj.find("address");
+		if (it == obj.end() || !it->second.is<std::string>()) {
+			return ErrorResponse(400, "bad_request",
+				"required string field `address` is missing (\"host:port\")");
+		}
+		address = it->second.get<std::string>();
+		const std::size_t colon = address.find(':');
+		if (colon == std::string::npos || colon == 0
+		    || colon == address.size() - 1) {
+			return ErrorResponse(400, "bad_request",
+				"`address` must be in \"host:port\" form");
+		}
+	}
+	std::string name;
+	{
+		const auto it = obj.find("name");
+		if (it != obj.end()) {
+			if (!it->second.is<std::string>()) {
+				return ErrorResponse(400, "bad_request",
+					"`name` must be a string");
+			}
+			name = it->second.get<std::string>();
+		}
+	}
+
+	std::unique_ptr<CECPacket> ec_req(new CECPacket(EC_OP_SERVER_ADD));
+	ec_req->AddTag(CECTag(EC_TAG_SERVER_ADDRESS,
+		wxString::FromUTF8(address.c_str())));
+	if (!name.empty()) {
+		ec_req->AddTag(CECTag(EC_TAG_SERVER_NAME,
+			wxString::FromUTF8(name.c_str())));
+	}
+
+	const CECPacket *ec_resp = m_app.SendRecvSerialized(ec_req.get());
+	if (!ec_resp) {
+		return ErrorResponse(503, "ec_unavailable",
+			"EC roundtrip failed for SERVER_ADD");
+	}
+	std::string ec_err_msg;
+	if (IsEcFailedResponse(ec_resp, ec_err_msg)) {
+		delete ec_resp;
+		return ErrorResponse(400, "amuled_rejected", ec_err_msg.c_str());
+	}
+	delete ec_resp;
+
+	// Inline refresh — the new server should be in the next /servers
+	// response without waiting on the regular tick.
+	(void) RefresherTick(m_app, m_state);
+
+	CHttpServer::Response r;
+	r.status       = 201;
+	r.content_type = "application/json";
+	CJsonWriter w;
+	w.BeginObject();
+	  w.Key("ok");      w.ValueBool(true);
+	  w.Key("address"); w.ValueString(wxString::FromUTF8(address.c_str()));
+	w.EndObject();
+	FinalizeJsonBody(w, r);
+	return r;
+}
+
+
+CHttpServer::Response CApiDispatcher::HandleServerConnect(
+	const CHttpServer::Request &req, const std::string &ecid_str)
+{
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations, m_authRateLimiter,
+		kSessionCookieName);
+	if (!a.ok) return a.rejection;
+	if (auto rej = RequireAdmin(a)) return *rej;
+
+	std::uint32_t ecid = 0;
+	if (!ParseEcidPath(ecid_str, ecid)) {
+		return ErrorResponse(400, "bad_request",
+			"path `{ecid}` must be a non-negative integer");
+	}
+	if (!m_state.HasFirstSnapshot()) {
+		return ErrorResponse(503, "ec_unavailable",
+			"amuleapi has not received its first EC snapshot yet");
+	}
+	webapi::ServerSnapshot srv;
+	if (!FindServerByEcid(m_state, ecid, srv)) {
+		return ErrorResponse(404, "not_found",
+			"no server with that ECID in the current snapshot");
+	}
+
+	// EC_OP_SERVER_CONNECT routes through Get_EC_Response_Server,
+	// which looks up the server by IPv4 lookup (ExternalConn.cpp:1266).
+	// Build EC_TAG_SERVER with the IPv4 + port from our cache.
+	std::unique_ptr<CECPacket> ec_req(new CECPacket(EC_OP_SERVER_CONNECT));
+	ec_req->AddTag(CECTag(EC_TAG_SERVER, EC_IPv4_t(srv.ip, srv.port)));
+
+	const CECPacket *ec_resp = m_app.SendRecvSerialized(ec_req.get());
+	if (!ec_resp) {
+		return ErrorResponse(503, "ec_unavailable",
+			"EC roundtrip failed for SERVER_CONNECT");
+	}
+	std::string ec_err_msg;
+	if (IsEcFailedResponse(ec_resp, ec_err_msg)) {
+		delete ec_resp;
+		return ErrorResponse(400, "amuled_rejected", ec_err_msg.c_str());
+	}
+	delete ec_resp;
+
+	// Connection state is observable via /status.ed2k.state — the
+	// refresher tick will surface the change. Inline refresh so
+	// /status reflects "connecting" immediately.
+	(void) RefresherTick(m_app, m_state);
+
+	CHttpServer::Response r;
+	r.status       = 202;
+	r.content_type = "application/json";
+	CJsonWriter w;
+	w.BeginObject();
+	  w.Key("ok");   w.ValueBool(true);
+	  w.Key("ecid"); w.ValueInt(static_cast<int64_t>(ecid));
+	w.EndObject();
+	FinalizeJsonBody(w, r);
+	return r;
+}
+
+
+CHttpServer::Response CApiDispatcher::HandleServerDelete(
+	const CHttpServer::Request &req, const std::string &ecid_str)
+{
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations, m_authRateLimiter,
+		kSessionCookieName);
+	if (!a.ok) return a.rejection;
+	if (auto rej = RequireAdmin(a)) return *rej;
+
+	std::uint32_t ecid = 0;
+	if (!ParseEcidPath(ecid_str, ecid)) {
+		return ErrorResponse(400, "bad_request",
+			"path `{ecid}` must be a non-negative integer");
+	}
+	if (!m_state.HasFirstSnapshot()) {
+		return ErrorResponse(503, "ec_unavailable",
+			"amuleapi has not received its first EC snapshot yet");
+	}
+	webapi::ServerSnapshot srv;
+	if (!FindServerByEcid(m_state, ecid, srv)) {
+		return ErrorResponse(404, "not_found",
+			"no server with that ECID in the current snapshot");
+	}
+
+	std::unique_ptr<CECPacket> ec_req(new CECPacket(EC_OP_SERVER_REMOVE));
+	ec_req->AddTag(CECTag(EC_TAG_SERVER, EC_IPv4_t(srv.ip, srv.port)));
+
+	const CECPacket *ec_resp = m_app.SendRecvSerialized(ec_req.get());
+	if (!ec_resp) {
+		return ErrorResponse(503, "ec_unavailable",
+			"EC roundtrip failed for SERVER_REMOVE");
+	}
+	std::string ec_err_msg;
+	if (IsEcFailedResponse(ec_resp, ec_err_msg)) {
+		delete ec_resp;
+		return ErrorResponse(400, "amuled_rejected", ec_err_msg.c_str());
+	}
+	delete ec_resp;
+
+	(void) RefresherTick(m_app, m_state);
+
+	CHttpServer::Response r;
+	r.status       = 200;
+	r.content_type = "application/json";
+	CJsonWriter w;
+	w.BeginObject();
+	  w.Key("ok");   w.ValueBool(true);
+	  w.Key("ecid"); w.ValueInt(static_cast<int64_t>(ecid));
+	w.EndObject();
+	FinalizeJsonBody(w, r);
+	return r;
+}
+
+
+CHttpServer::Response CApiDispatcher::HandleServerUpdateFromUrl(
+	const CHttpServer::Request &req)
+{
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations, m_authRateLimiter,
+		kSessionCookieName);
+	if (!a.ok) return a.rejection;
+	if (auto rej = RequireAdmin(a)) return *rej;
+
+	picojson::value root;
+	std::string parse_err;
+	if (!ParseJsonObjectBody(req.body, root, parse_err)) {
+		return ErrorResponse(400, "bad_request", parse_err.c_str());
+	}
+	const auto &obj = root.get<picojson::object>();
+	const auto it = obj.find("servers_url");
+	if (it == obj.end() || !it->second.is<std::string>()) {
+		return ErrorResponse(400, "bad_request",
+			"required string field `servers_url` is missing");
+	}
+	const std::string &url = it->second.get<std::string>();
+	if (url.empty()) {
+		return ErrorResponse(400, "bad_request",
+			"`servers_url` must not be empty");
+	}
+	// Light hygiene check — amuled will fetch this and bail if it's
+	// nonsense, but rejecting obviously bad inputs at the API layer
+	// gives a clearer error than the EC "amuled rejected" wrapper.
+	if (url.compare(0, 7, "http://") != 0
+	    && url.compare(0, 8, "https://") != 0) {
+		return ErrorResponse(400, "bad_request",
+			"`servers_url` must be an http://or https://URL");
+	}
+
+	std::unique_ptr<CECPacket> ec_req(
+		new CECPacket(EC_OP_SERVER_UPDATE_FROM_URL));
+	ec_req->AddTag(CECTag(EC_TAG_SERVERS_UPDATE_URL,
+		wxString::FromUTF8(url.c_str())));
+	const CECPacket *ec_resp = m_app.SendRecvSerialized(ec_req.get());
+	if (!ec_resp) {
+		return ErrorResponse(503, "ec_unavailable",
+			"EC roundtrip failed");
+	}
+	std::string ec_err;
+	if (IsEcFailedResponse(ec_resp, ec_err)) {
+		delete ec_resp;
+		return ErrorResponse(400, "amuled_rejected", ec_err.c_str());
+	}
+	delete ec_resp;
+
+	// amuled streams the new server list into its CServerList
+	// asynchronously over the next few ticks (download + parse + merge
+	// in CServerList::UpdateServerMetFromURL). Run the inline
+	// RefresherTick to grab whatever's already there, but the
+	// `server_added` SSE events will continue to fire on subsequent
+	// natural ticks as more entries land.
+	(void) RefresherTick(m_app, m_state);
+
+	CHttpServer::Response r;
+	r.status       = 202;
+	r.content_type = "application/json";
+	CJsonWriter w;
+	w.BeginObject();
+	  w.Key("ok");          w.ValueBool(true);
+	  w.Key("servers_url"); w.ValueString(wxString::FromUTF8(url.c_str()));
+	w.EndObject();
+	FinalizeJsonBody(w, r);
+	return r;
+}
+
+
+// Resolve "<ip>:<port>" from the URL into an ECID by walking the
+// servers cache. Returns 0 on miss; the caller 404s.
+static std::uint32_t ResolveServerEcidByAddress(
+	const webapi::CState &state, const std::string &ip_port)
+{
+	const auto colon = ip_port.rfind(':');
+	if (colon == std::string::npos) return 0;
+	const std::string ip_str = ip_port.substr(0, colon);
+	const std::string port_str = ip_port.substr(colon + 1);
+	if (ip_str.empty() || port_str.empty()) return 0;
+	char *end = nullptr;
+	const unsigned long port = std::strtoul(port_str.c_str(), &end, 10);
+	if (end == port_str.c_str() || *end != '\0'
+	    || port == 0 || port > 0xFFFF) {
+		return 0;
+	}
+	// Parse the IP — accept dotted-quad form OR a uint32 host-order
+	// number that matches ServerSnapshot::ip. We compute both so we
+	// can match either against what the cache holds.
+	std::uint32_t ip_he = 0;
+	{
+		unsigned a_, b_, c_, d_;
+		if (std::sscanf(ip_str.c_str(), "%u.%u.%u.%u",
+		                &a_, &b_, &c_, &d_) == 4
+		    && a_ <= 255 && b_ <= 255 && c_ <= 255 && d_ <= 255) {
+			ip_he = (a_) | (b_ << 8) | (c_ << 16) | (d_ << 24);
+		}
+	}
+	// Require an IPv4-shaped address: drop the s.address string
+	// fallback. The fallback was a convenience for hostname-form
+	// URLs (e.g. `/api/v0/servers/donkey.example.com:4242/connect`),
+	// but it admits an UNINTENDED match too — `s.address` is
+	// populated from amuled's wire-form "name" tag, which can be
+	// a hostname OR a synthetic display string ("Eserver No.1");
+	// a DELETE-by-address with a colliding label could remove the
+	// wrong row. IP+port exact match has no such ambiguity.
+	if (ip_he == 0) return 0;
+	for (const auto &s : state.Servers()) {
+		if (s.port == static_cast<std::uint16_t>(port)
+		    && s.ip == ip_he) {
+			return s.ecid;
+		}
+	}
+	return 0;
+}
+
+
+CHttpServer::Response CApiDispatcher::HandleServerConnectByAddress(
+	const CHttpServer::Request &req, const std::string &ip_port)
+{
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations, m_authRateLimiter,
+		kSessionCookieName);
+	if (!a.ok) return a.rejection;
+	if (auto rej = RequireAdmin(a)) return *rej;
+	if (!m_state.HasFirstSnapshot()) {
+		return ErrorResponse(503, "ec_unavailable",
+			"amuleapi has not received its first EC snapshot yet");
+	}
+	const std::uint32_t ecid =
+		ResolveServerEcidByAddress(m_state, ip_port);
+	if (ecid == 0) {
+		return ErrorResponse(404, "not_found",
+			"no server matches that ip:port");
+	}
+	// Delegate to the ECID-keyed handler; passing the resolved ECID as
+	// a decimal string keeps the contract uniform.
+	std::ostringstream os; os << ecid;
+	return HandleServerConnect(req, os.str());
+}
+
+
+CHttpServer::Response CApiDispatcher::HandleServerDeleteByAddress(
+	const CHttpServer::Request &req, const std::string &ip_port)
+{
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations, m_authRateLimiter,
+		kSessionCookieName);
+	if (!a.ok) return a.rejection;
+	if (auto rej = RequireAdmin(a)) return *rej;
+	if (!m_state.HasFirstSnapshot()) {
+		return ErrorResponse(503, "ec_unavailable",
+			"amuleapi has not received its first EC snapshot yet");
+	}
+	const std::uint32_t ecid =
+		ResolveServerEcidByAddress(m_state, ip_port);
+	if (ecid == 0) {
+		return ErrorResponse(404, "not_found",
+			"no server matches that ip:port");
+	}
+	std::ostringstream os; os << ecid;
+	return HandleServerDelete(req, os.str());
+}
+
+
+CHttpServer::Response CApiDispatcher::HandleCategories(const CHttpServer::Request &req)
+{
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations, m_authRateLimiter,
+		kSessionCookieName);
+	if (!a.ok) return a.rejection;
+	// amuled's EC suppresses the whole `EC_TAG_PREFS_CATEGORIES`
+	// block when no custom categories exist, and starts including
+	// index 0 once the first custom one is added. Faithful at the
+	// wire layer, but a client iterating /categories expecting at
+	// least the default has to special-case the empty case. Inject
+	// a synthetic index-0 entry when missing so clients see the same
+	// shape regardless of category count. The defaults mirror what
+	// amuled emits for category 0 itself: empty title/path/comment,
+	// color 0, priority_code PR_LOW (the amuled default for
+	// `defaultcat->prio` in CPreferences::LoadCats).
+	std::vector<webapi::CategorySnapshot> cats = m_state.Categories();
+	bool has_zero = false;
+	for (const auto &c : cats) {
+		if (c.index == 0) { has_zero = true; break; }
+	}
+	if (!has_zero) {
+		webapi::CategorySnapshot d;
+		d.index = 0;
+		d.priority_code = 0;        // PR_LOW (matches amuled default)
+		d.priority      = "low";
+		cats.insert(cats.begin(), std::move(d));
+	}
+	return ListResponse(m_state, "categories", cats, WriteCategoryObject);
+}
+
+
+CHttpServer::Response CApiDispatcher::HandleKad(const CHttpServer::Request &req)
+{
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations, m_authRateLimiter,
+		kSessionCookieName);
+	if (!a.ok) return a.rejection;
+	if (!m_state.HasFirstSnapshot()) {
+		return ErrorResponse(503, "ec_unavailable",
+			"amuleapi has not received its first EC snapshot yet");
+	}
+
+	const webapi::KadSnapshot k = m_state.Kad();
+	CHttpServer::Response r;
+	r.status       = 200;
+	r.content_type = "application/json";
+	CJsonWriter w;
+	w.BeginObject();
+	  // Bare object (Q3 — Kad is a single resource, not a list).
+	  w.Key("state");            w.ValueString(wxString::FromUTF8(k.state.c_str()));
+	  w.Key("firewalled");       w.ValueBool(k.firewalled);
+	  w.Key("firewalled_udp");   w.ValueBool(k.firewalled_udp);
+	  w.Key("in_lan_mode");      w.ValueBool(k.in_lan_mode);
+	  w.Key("ip");               w.ValueString(wxString::FromUTF8(k.ip.c_str()));
+	  w.Key("network");
+	  w.BeginObject();
+	    w.Key("users"); w.ValueInt(static_cast<int64_t>(k.users));
+	    w.Key("files"); w.ValueInt(static_cast<int64_t>(k.files));
+	    w.Key("nodes"); w.ValueInt(static_cast<int64_t>(k.nodes));
+	  w.EndObject();
+	  w.Key("indexed");
+	  w.BeginObject();
+	    w.Key("sources");  w.ValueInt(static_cast<int64_t>(k.indexed_sources));
+	    w.Key("keywords"); w.ValueInt(static_cast<int64_t>(k.indexed_keywords));
+	    w.Key("notes");    w.ValueInt(static_cast<int64_t>(k.indexed_notes));
+	    w.Key("load");     w.ValueInt(static_cast<int64_t>(k.indexed_load));
+	  w.EndObject();
+	  w.Key("buddy");
+	  w.BeginObject();
+	    w.Key("status"); w.ValueString(wxString::FromUTF8(k.buddy_status.c_str()));
+	    w.Key("ip");     w.ValueString(wxString::FromUTF8(k.buddy_ip.c_str()));
+	    w.Key("port");   w.ValueInt(static_cast<int64_t>(k.buddy_port));
+	  w.EndObject();
+	w.EndObject();
+	FinalizeJsonBody(w, r);
+	return r;
+}
+
+
+namespace {
+
+// `?tail=N` parser. Returns 0 if the query is absent / unparseable;
+// the caller's contract is "0 means return everything". Negative or
+// non-numeric values clamp to 0.
+std::size_t ParseTailParam(const std::string &query)
+{
+	const auto qmap = web_api_path::ParseQuery(query);
+	const auto it = qmap.find("tail");
+	if (it == qmap.end()) return 0;
+	const long n = std::atol(it->second.c_str());
+	if (n <= 0) return 0;
+	// Cap at 100k lines so a bogus `?tail=2147483647` doesn't try to
+	// serialise the entire wxString through the JSON escaper.
+	const long capped = std::min<long>(n, 100000);
+	return static_cast<std::size_t>(capped);
+}
+
+
+// Return a copy of `all` containing at most `tail` trailing lines.
+// `tail == 0` means "all lines" (no tailing).
+std::vector<std::string> SliceTail(const std::vector<std::string> &all,
+                                   std::size_t tail)
+{
+	if (tail == 0 || all.size() <= tail) return all;
+	return std::vector<std::string>(
+		all.begin() + (all.size() - tail), all.end());
+}
+
+
+// For a single-string log (e.g. /logs/serverinfo), `?tail=N` slices
+// at line boundaries from the END so the first line of the response
+// is always whole. tail=0 returns the input verbatim.
+std::string TailString(const std::string &text, std::size_t tail_lines)
+{
+	if (tail_lines == 0 || text.empty()) return text;
+	// Walk backwards counting newlines until we've found `tail_lines`
+	// of them; whatever's after the last seen newline becomes the
+	// response.
+	std::size_t pos = text.size();
+	std::size_t seen = 0;
+	while (pos > 0 && seen < tail_lines) {
+		--pos;
+		if (text[pos] == '\n') ++seen;
+	}
+	// Advance past the leading '\n' so the response doesn't start
+	// with a blank line.
+	if (pos < text.size() && text[pos] == '\n') ++pos;
+	return text.substr(pos);
+}
+
+}  // namespace
+
+
+namespace {
+
+void WriteStatsNode(CJsonWriter &w, const webapi::StatsTreeNode &n)
+{
+	w.BeginObject();
+	  w.Key("label"); w.ValueString(wxString::FromUTF8(n.label.c_str()));
+	  w.Key("children");
+	  w.BeginArray();
+	  for (const auto &c : n.children) WriteStatsNode(w, c);
+	  w.EndArray();
+	w.EndObject();
+}
+
+
+// Render an array of (t, value) points walking backwards from
+// snapshot_at. Earliest sample sits at points[start] and corresponds
+// to `snapshot_at - (samples.size()-1)*interval`; most recent sits
+// at `snapshot_at`.
+void WritePointArray(CJsonWriter &w,
+                     const std::vector<std::uint32_t> &samples,
+                     std::time_t snapshot_at,
+                     std::uint32_t interval,
+                     std::size_t max_width)
+{
+	w.BeginArray();
+	if (samples.empty()) { w.EndArray(); return; }
+	const std::size_t start = (max_width > 0 && samples.size() > max_width)
+		? samples.size() - max_width : 0;
+	for (std::size_t i = start; i < samples.size(); ++i) {
+		const std::time_t t = snapshot_at
+			- static_cast<std::time_t>(
+				(samples.size() - 1 - i) * interval);
+		w.BeginObject();
+		  w.Key("t");        w.ValueString(wxString::FromUTF8(
+		                       webapi::FormatIso8601Utc(t).c_str()));
+		  w.Key("t_unix");   w.ValueInt(static_cast<int64_t>(t));
+		  w.Key("value");    w.ValueInt(static_cast<int64_t>(samples[i]));
+		w.EndObject();
+	}
+	w.EndArray();
+}
+
+
+void WriteSearchObject(CJsonWriter &w, const webapi::SearchResult &r)
+{
+	w.BeginObject();
+	  w.Key("hash");         w.ValueString(wxString::FromUTF8(r.hash.c_str()));
+	  w.Key("name");         w.ValueString(wxString::FromUTF8(r.name.c_str()));
+	  w.Key("size");         w.ValueInt(static_cast<int64_t>(r.size));
+	  w.Key("sources");
+	  w.BeginObject();
+	    w.Key("total");      w.ValueInt(static_cast<int64_t>(r.source_count));
+	    w.Key("complete");   w.ValueInt(static_cast<int64_t>(r.complete_source_count));
+	  w.EndObject();
+	  w.Key("already_have"); w.ValueBool(r.already_have);
+	  w.Key("rating");       w.ValueInt(static_cast<int64_t>(r.rating));
+	w.EndObject();
+}
+
+}  // namespace
+
+
+CHttpServer::Response CApiDispatcher::HandleStatsTree(const CHttpServer::Request &req)
+{
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations, m_authRateLimiter,
+		kSessionCookieName);
+	if (!a.ok) return a.rejection;
+
+	// lazy-fetch with 1 s TTL coalescing. The fetcher runs
+	// the EC roundtrip under m_app's m_ec_mtx (SendRecvSerialized);
+	// concurrent burst reads serialize on m_stats_tree_cache's mutex
+	// and the second waiter reads the just-stored value.
+	auto pair = m_stats_tree_cache.GetOrFetch(
+		std::chrono::milliseconds(1000),
+		[this]() -> TtlPair_StatsTree {
+			std::unique_ptr<CECPacket> req_ec(
+				new CECPacket(EC_OP_GET_STATSTREE, EC_DETAIL_WEB));
+			req_ec->AddTag(CECTag(EC_TAG_STATTREE_CAPPING,
+				static_cast<std::uint8_t>(0)));
+			const CECPacket *resp = m_app.SendRecvSerialized(req_ec.get());
+			webapi::StatsTreeNode tree;
+			std::time_t ts = 0;
+			if (resp) {
+				webapi::ParseStatsTreeFromPacket(resp, tree);
+				ts = std::time(nullptr);
+				delete resp;
+			}
+			return TtlPair_StatsTree(std::move(tree), ts);
+		});
+
+	if (pair.second == 0) {
+		return ErrorResponse(503, "ec_unavailable",
+			"EC fetch failed for stats tree; amuled may be disconnected");
+	}
+
+	const webapi::StatsTreeNode &root = pair.first;
+	const std::time_t ts = pair.second;
+
+	CHttpServer::Response r;
+	r.status       = 200;
+	r.content_type = "application/json";
+	// snapshot_at retired in favour of the ETag
+	// as the cache validator. The TtlPair_StatsTree still tracks the
+	// fetched-at time internally (drives the 1 s TTL coalescer) — it
+	// just isn't surfaced any more.
+	(void) ts;
+	CJsonWriter w;
+	w.BeginObject();
+	  w.Key("nodes");
+	  w.BeginArray();
+	  for (const auto &child : root.children) WriteStatsNode(w, child);
+	  w.EndArray();
+	w.EndObject();
+	FinalizeJsonBody(w, r);
+	return r;
+}
+
+
+CHttpServer::Response CApiDispatcher::HandleStatsGraph(
+	const CHttpServer::Request &req, const std::string &graph)
+{
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations, m_authRateLimiter,
+		kSessionCookieName);
+	if (!a.ok) return a.rejection;
+
+	// Validate the graph name BEFORE fetching — saves an EC roundtrip
+	// on tab-complete typos hitting /stats/graphs/<bogus>.
+	const char *unit = nullptr;
+	if      (graph == "download")    { unit = "bps"; }
+	else if (graph == "upload")      { unit = "bps"; }
+	else if (graph == "connections") { unit = "count"; }
+	else if (graph == "kad")         { unit = "count"; }
+	else {
+		return ErrorResponse(404, "not_found",
+			"unknown graph; expected one of: download, upload, connections, kad");
+	}
+
+	// Lazy-fetch the full 4-series graph bundle (one EC call serves
+	// all 4 named graphs, so the cache shares across concurrent
+	// requests for different graph names).
+	auto pair = m_stats_graphs_cache.GetOrFetch(
+		std::chrono::milliseconds(1000),
+		[this]() -> TtlPair_StatsGraphs {
+			std::unique_ptr<CECPacket> req_ec(new CECPacket(EC_OP_GET_STATSGRAPHS));
+			req_ec->AddTag(CECTag(EC_TAG_STATSGRAPH_SCALE,
+				static_cast<std::uint16_t>(1)));
+			req_ec->AddTag(CECTag(EC_TAG_STATSGRAPH_WIDTH,
+				static_cast<std::uint16_t>(1800)));
+			const CECPacket *resp = m_app.SendRecvSerialized(req_ec.get());
+			webapi::StatsGraphs g;
+			std::time_t ts = 0;
+			if (resp) {
+				webapi::ParseGraphsFromPacket(resp, g);
+				ts = std::time(nullptr);
+				delete resp;
+			}
+			return TtlPair_StatsGraphs(std::move(g), ts);
+		});
+
+	if (pair.second == 0) {
+		return ErrorResponse(503, "ec_unavailable",
+			"EC fetch failed for stats graphs; amuled may be disconnected");
+	}
+
+	const webapi::StatsGraphs &g = pair.first;
+	const std::vector<std::uint32_t> *series = nullptr;
+	if      (graph == "download")    { series = &g.download_bps; }
+	else if (graph == "upload")      { series = &g.upload_bps;   }
+	else if (graph == "connections") { series = &g.connections;  }
+	else /* kad */                   { series = &g.kad_nodes;    }
+
+	// ?width=N — clamp the sample count returned. 0 / absent means
+	// "everything we have" (up to the 1800-sample window we ask for).
+	std::string query;
+	const std::size_t q = req.target.find('?');
+	if (q != std::string::npos) query = req.target.substr(q + 1);
+	std::size_t width = 0;
+	{
+		const auto qmap = web_api_path::ParseQuery(query);
+		const auto it = qmap.find("width");
+		if (it != qmap.end()) {
+			const long n = std::atol(it->second.c_str());
+			if (n > 0) width = static_cast<std::size_t>(std::min<long>(n, 1800));
+		}
+	}
+
+	const std::time_t ts = pair.second;
+	CHttpServer::Response r;
+	r.status       = 200;
+	r.content_type = "application/json";
+	CJsonWriter w;
+	w.BeginObject();
+	  w.Key("graph");            w.ValueString(wxString::FromUTF8(graph.c_str()));
+	  w.Key("unit");             w.ValueString(wxString::FromUTF8(unit));
+	  w.Key("interval_seconds"); w.ValueInt(static_cast<int64_t>(g.interval_seconds));
+	  // snapshot_at retired from the response. WritePointArray
+	  // still consumes `ts` to compute per-point timestamps (anchoring
+	  // the time-series backwards from the fetch wall-clock).
+	  w.Key("points");
+	  WritePointArray(w, *series, ts, g.interval_seconds, width);
+	  // Session totals tag along — clients showing "this session: X GB
+	  // down" don't need a separate roundtrip.
+	  w.Key("session");
+	  w.BeginObject();
+	    w.Key("download_bytes"); w.ValueInt(static_cast<int64_t>(g.session_download_bytes));
+	    w.Key("upload_bytes");   w.ValueInt(static_cast<int64_t>(g.session_upload_bytes));
+	    w.Key("kad_bytes");      w.ValueInt(static_cast<int64_t>(g.session_kad_bytes));
+	  w.EndObject();
+	w.EndObject();
+	FinalizeJsonBody(w, r);
+	return r;
+}
+
+
+CHttpServer::Response CApiDispatcher::HandleSearchResults(const CHttpServer::Request &req)
+{
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations, m_authRateLimiter,
+		kSessionCookieName);
+	if (!a.ok) return a.rejection;
+
+	// Read straight from the refresher-maintained state. POST /search
+	// flips the active flag; RefresherTick polls amuled while active and
+	// reads the daemon's unambiguous EC_TAG_SEARCH_LIFECYCLE_* tags
+	// (state + unified percent) — see RefresherTick.cpp + SearchList.cpp.
+	// The state stores the normalized (kind, percent, complete, active);
+	// no further interpretation here. The `progress` object carries the
+	// same state/kind/percent as the `search_progress` SSE event (the
+	// event additionally ships a results count, since it has no results
+	// array beside it).
+	const std::vector<webapi::SearchResult> results_vec = m_state.Search();
+	const webapi::SearchProgressSnapshot    progress    = m_state.SearchProgress();
+
+	CHttpServer::Response r;
+	r.status       = 200;
+	r.content_type = "application/json";
+	CJsonWriter w;
+	w.BeginObject();
+	  w.Key("results");
+	  w.BeginArray();
+	  for (const auto &item : results_vec) WriteSearchObject(w, item);
+	  w.EndArray();
+	  // Mirrors the `search_progress` SSE event field-for-field. `state`
+	  // is canonical and encodes the full lifecycle (running / finished /
+	  // idle), so we don't also emit redundant `active` / `complete`
+	  // booleans — consumers derive them from `state` and read the same
+	  // shape whether they poll here or subscribe to the stream.
+	  w.Key("progress");
+	  w.BeginObject();
+	    w.Key("state");    w.ValueString(wxString::FromAscii(
+	                         progress.complete ? "finished"
+	                       : progress.active   ? "running" : "idle"));
+	    w.Key("kind");     w.ValueString(wxString::FromUTF8(progress.kind.c_str()));
+	    w.Key("percent");  w.ValueInt(static_cast<int64_t>(progress.percent));
+	  w.EndObject();
+	w.EndObject();
+	FinalizeJsonBody(w, r);
+	return r;
+}
+
+
+CHttpServer::Response CApiDispatcher::HandleLogAmule(const CHttpServer::Request &req)
+{
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations, m_authRateLimiter,
+		kSessionCookieName);
+	if (!a.ok) return a.rejection;
+
+	// Extract the query string from the raw target (request.target is
+	// the literal URI, e.g. "/api/v0/logs/amule?tail=200").
+	std::string path, query;
+	const size_t q = req.target.find('?');
+	if (q != std::string::npos) {
+		query = req.target.substr(q + 1);
+	}
+	const std::size_t tail = ParseTailParam(query);
+	const auto all = m_state.AmuleLog();
+	const auto sliced = SliceTail(all, tail);
+
+	// Bare object (Q3): single resource, no list envelope.
+	CHttpServer::Response r;
+	r.status       = 200;
+	r.content_type = "application/json";
+	CJsonWriter w;
+	w.BeginObject();
+	  w.Key("lines");
+	  w.BeginArray();
+	  for (const auto &line : sliced) {
+	    w.ValueString(wxString::FromUTF8(line.c_str()));
+	  }
+	  w.EndArray();
+	  // Operator-debug metadata: total cached + how many we returned.
+	  // Lets a client paging through history know what it missed.
+	  w.Key("total_cached");  w.ValueInt(static_cast<int64_t>(all.size()));
+	  w.Key("returned");      w.ValueInt(static_cast<int64_t>(sliced.size()));
+	w.EndObject();
+	FinalizeJsonBody(w, r);
+	return r;
+}
+
+
+CHttpServer::Response CApiDispatcher::HandleLogAmuleReset(
+	const CHttpServer::Request &req)
+{
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations, m_authRateLimiter,
+		kSessionCookieName);
+	if (!a.ok) return a.rejection;
+	if (auto rej = RequireAdmin(a)) return *rej;
+
+	std::unique_ptr<CECPacket> ec_req(new CECPacket(EC_OP_RESET_LOG));
+	const CECPacket *ec_resp = m_app.SendRecvSerialized(ec_req.get());
+	if (!ec_resp) {
+		return ErrorResponse(503, "ec_unavailable",
+			"EC roundtrip failed");
+	}
+	std::string ec_err;
+	if (IsEcFailedResponse(ec_resp, ec_err)) {
+		delete ec_resp;
+		return ErrorResponse(400, "amuled_rejected", ec_err.c_str());
+	}
+	delete ec_resp;
+
+	// Drop the in-process mirror. The refresher's append-only path
+	// (AppendAmuleLog) can't shrink the cache, and EmitDiffsAndUpdate
+	// already treats a size decrease as a silent truncation
+	// (EventDiff.cpp's `amule_log.size() < prev.amule_log_count`
+	// branch), so no spurious log_appended event fires on the next
+	// tick.
+	m_state.ClearAmuleLog();
+
+	CHttpServer::Response r;
+	r.status       = 204;
+	r.content_type.clear();
+	return r;
+}
+
+
+CHttpServer::Response CApiDispatcher::HandleLogServerinfo(const CHttpServer::Request &req)
+{
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations, m_authRateLimiter,
+		kSessionCookieName);
+	if (!a.ok) return a.rejection;
+
+	std::string query;
+	const size_t q = req.target.find('?');
+	if (q != std::string::npos) {
+		query = req.target.substr(q + 1);
+	}
+	const std::size_t tail = ParseTailParam(query);
+
+	// Lazy-fetch via TtlCache. EC_OP_GET_SERVERINFO ships one
+	// EC_TAG_STRING with the whole accumulated text — amuled rotates
+	// it server-side so the size stays bounded.
+	auto pair = m_server_info_cache.GetOrFetch(
+		std::chrono::milliseconds(1000),
+		[this]() -> TtlPair_ServerInfo {
+			std::unique_ptr<CECPacket> req_ec(
+				new CECPacket(EC_OP_GET_SERVERINFO));
+			const CECPacket *resp = m_app.SendRecvSerialized(req_ec.get());
+			webapi::ServerInfoLog log;
+			std::time_t ts = 0;
+			if (resp) {
+				if (const CECTag *t = resp->GetFirstTagSafe()) {
+					if (t->GetTagName() == EC_TAG_STRING) {
+						log.text = std::string(t->GetStringData().utf8_str());
+					}
+				}
+				ts = std::time(nullptr);
+				delete resp;
+			}
+			return TtlPair_ServerInfo(std::move(log), ts);
+		});
+
+	if (pair.second == 0) {
+		return ErrorResponse(503, "ec_unavailable",
+			"EC fetch failed for server info; amuled may be disconnected");
+	}
+
+	const webapi::ServerInfoLog &log = pair.first;
+	const std::string text = TailString(log.text, tail);
+
+	CHttpServer::Response r;
+	r.status       = 200;
+	r.content_type = "application/json";
+	CJsonWriter w;
+	w.BeginObject();
+	  w.Key("text");          w.ValueString(wxString::FromUTF8(text.c_str()));
+	  // The total length lets a client decide whether to re-poll
+	  // with a smaller `?tail=` for incremental display.
+	  w.Key("total_bytes");   w.ValueInt(static_cast<int64_t>(log.text.size()));
+	  w.Key("returned_bytes"); w.ValueInt(static_cast<int64_t>(text.size()));
+	w.EndObject();
+	FinalizeJsonBody(w, r);
+	return r;
+}
+
+
+CHttpServer::Response CApiDispatcher::HandleLogServerinfoReset(
+	const CHttpServer::Request &req)
+{
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations, m_authRateLimiter,
+		kSessionCookieName);
+	if (!a.ok) return a.rejection;
+	if (auto rej = RequireAdmin(a)) return *rej;
+
+	std::unique_ptr<CECPacket> ec_req(
+		new CECPacket(EC_OP_CLEAR_SERVERINFO));
+	const CECPacket *ec_resp = m_app.SendRecvSerialized(ec_req.get());
+	if (!ec_resp) {
+		return ErrorResponse(503, "ec_unavailable",
+			"EC roundtrip failed");
+	}
+	std::string ec_err;
+	if (IsEcFailedResponse(ec_resp, ec_err)) {
+		delete ec_resp;
+		return ErrorResponse(400, "amuled_rejected", ec_err.c_str());
+	}
+	delete ec_resp;
+
+	// Lazy cache for /logs/serverinfo would otherwise return stale
+	// text until its 1 s TTL expires; force the next GET to re-fetch.
+	m_server_info_cache.Invalidate();
+
+	CHttpServer::Response r;
+	r.status       = 204;
+	r.content_type.clear();
+	return r;
+}
+
+
+CHttpServer::Response CApiDispatcher::HandlePreferences(const CHttpServer::Request &req)
+{
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations, m_authRateLimiter,
+		kSessionCookieName);
+	if (!a.ok) return a.rejection;
+	if (!m_state.HasFirstSnapshot()) {
+		return ErrorResponse(503, "ec_unavailable",
+			"amuleapi has not received its first EC snapshot yet");
+	}
+
+	const webapi::PreferencesSnapshot p = m_state.Preferences();
+	CHttpServer::Response r;
+	r.status       = 200;
+	r.content_type = "application/json";
+	CJsonWriter w;
+	w.BeginObject();
+	  w.Key("general");
+	  w.BeginObject();
+	    w.Key("nickname");          w.ValueString(wxString::FromUTF8(p.nickname.c_str()));
+	    w.Key("user_hash");         w.ValueString(wxString::FromUTF8(p.user_hash.c_str()));
+	    w.Key("host_name");         w.ValueString(wxString::FromUTF8(p.host_name.c_str()));
+	    w.Key("check_new_version"); w.ValueBool(p.check_new_version);
+	  w.EndObject();
+	  w.Key("connection");
+	  w.BeginObject();
+	    w.Key("max_upload_kbps");       w.ValueInt(static_cast<int64_t>(p.max_upload_kbps));
+	    w.Key("max_download_kbps");     w.ValueInt(static_cast<int64_t>(p.max_download_kbps));
+	    w.Key("max_upload_cap_kbps");   w.ValueInt(static_cast<int64_t>(p.max_upload_cap_kbps));
+	    w.Key("max_download_cap_kbps"); w.ValueInt(static_cast<int64_t>(p.max_download_cap_kbps));
+	    w.Key("slot_allocation");       w.ValueInt(static_cast<int64_t>(p.slot_allocation));
+	    w.Key("tcp_port");              w.ValueInt(static_cast<int64_t>(p.tcp_port));
+	    w.Key("udp_port");              w.ValueInt(static_cast<int64_t>(p.udp_port));
+	    w.Key("udp_disabled");          w.ValueBool(p.udp_disabled);
+	    w.Key("max_sources_per_file");  w.ValueInt(static_cast<int64_t>(p.max_sources_per_file));
+	    w.Key("max_connections");       w.ValueInt(static_cast<int64_t>(p.max_connections));
+	    w.Key("autoconnect");           w.ValueBool(p.autoconnect);
+	    w.Key("reconnect");             w.ValueBool(p.reconnect);
+	    w.Key("network_ed2k");          w.ValueBool(p.network_ed2k);
+	    w.Key("network_kad");           w.ValueBool(p.network_kad);
+	  w.EndObject();
+	w.EndObject();
+	FinalizeJsonBody(w, r);
+	return r;
+}
+
+
+
+namespace {
+
+// Helpers that pull (& validate) optional fields from a JSON object.
+// Each returns true and writes `out` if the field is present and the
+// right shape; returns false on absence. On wrong shape, writes
+// `err_label` for the caller to relay to the client and returns false
+// as well (errors take priority via the err_label out-param).
+struct PrefsParseError {
+	bool        is_error = false;
+	std::string message;
+};
+
+// EC_OP_SET_PREFERENCES requires EC_DETAIL_FULL so the daemon honors
+// boolean tags (CEC_Prefs_Packet::Apply checks
+// `use_tag = (GetDetailLevel() == EC_DETAIL_FULL)` before calling
+// ApplyBoolean). FULL is also what amulegui sends.
+}  // namespace
+
+CHttpServer::Response CApiDispatcher::HandlePreferencesPatch(
+	const CHttpServer::Request &req)
+{
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations, m_authRateLimiter,
+		kSessionCookieName);
+	if (!a.ok) return a.rejection;
+	if (auto rej = RequireAdmin(a)) return *rej;
+
+	picojson::value root;
+	std::string parse_err;
+	if (!ParseJsonObjectBody(req.body, root, parse_err)) {
+		return ErrorResponse(400, "bad_request", parse_err.c_str());
+	}
+	const auto &obj = root.get<picojson::object>();
+
+	// Body shape: { "general": {...}, "connection": {...} } — both
+	// sub-objects optional, all fields within optional. Mirrors the
+	// /preferences GET shape so a typical client read-
+	// modify-write workflow doesn't have to translate between schemas.
+	const picojson::object *general_obj    = nullptr;
+	const picojson::object *connection_obj = nullptr;
+	{
+		const auto it = obj.find("general");
+		if (it != obj.end()) {
+			if (!it->second.is<picojson::object>()) {
+				return ErrorResponse(400, "bad_request",
+					"`general` must be an object");
+			}
+			general_obj = &it->second.get<picojson::object>();
+		}
+	}
+	{
+		const auto it = obj.find("connection");
+		if (it != obj.end()) {
+			if (!it->second.is<picojson::object>()) {
+				return ErrorResponse(400, "bad_request",
+					"`connection` must be an object");
+			}
+			connection_obj = &it->second.get<picojson::object>();
+		}
+	}
+
+	if (general_obj == nullptr && connection_obj == nullptr) {
+		return ErrorResponse(400, "bad_request",
+			"request body must include at least one of `general` or "
+			"`connection` sub-objects");
+	}
+
+	// Build the SET_PREFERENCES packet at EC_DETAIL_FULL (required for
+	// boolean fields — Apply() gates ApplyBoolean on detail==FULL).
+	std::unique_ptr<CECPacket> ec_req(
+		new CECPacket(EC_OP_SET_PREFERENCES, EC_DETAIL_FULL));
+
+	auto add_uint = [](CECTag &group, ec_tagname_t name,
+	                   std::uint32_t v) {
+		group.AddTag(CECTag(name, v));
+	};
+	auto add_bool = [](CECTag &group, ec_tagname_t name, bool v) {
+		group.AddTag(CECTag(name, static_cast<std::uint8_t>(v ? 1 : 0)));
+	};
+
+	bool any_change = false;
+
+	// --- General sub-object. -----------------------------------
+	if (general_obj) {
+		CECTag general(EC_TAG_PREFS_GENERAL, static_cast<std::uint32_t>(0));
+		bool any_general = false;
+		{
+			const auto it = general_obj->find("nickname");
+			if (it != general_obj->end()) {
+				if (!it->second.is<std::string>()) {
+					return ErrorResponse(400, "bad_request",
+						"`general.nickname` must be a string");
+				}
+				const std::string &v = it->second.get<std::string>();
+				general.AddTag(CECTag(EC_TAG_USER_NICK,
+					wxString::FromUTF8(v.c_str())));
+				any_general = true;
+			}
+		}
+		{
+			const auto it = general_obj->find("check_new_version");
+			if (it != general_obj->end()) {
+				if (!it->second.is<bool>()) {
+					return ErrorResponse(400, "bad_request",
+						"`general.check_new_version` must be a bool");
+				}
+				add_bool(general, EC_TAG_GENERAL_CHECK_NEW_VERSION,
+					it->second.get<bool>());
+				any_general = true;
+			}
+		}
+		if (any_general) {
+			ec_req->AddTag(general);
+			any_change = true;
+		}
+	}
+
+	// --- Connection sub-object. --------------------------------
+	if (connection_obj) {
+		CECTag connection(EC_TAG_PREFS_CONNECTIONS, static_cast<std::uint32_t>(0));
+		bool any_conn = false;
+
+		// Helper for "uint field" — repeats for each numeric pref.
+		auto take_uint = [&](const char *key, ec_tagname_t name,
+		                     std::uint32_t max) -> CHttpServer::Response {
+			const auto it = connection_obj->find(key);
+			if (it == connection_obj->end()) {
+				CHttpServer::Response ok;
+				ok.status = 0;   // sentinel: not present
+				return ok;
+			}
+			if (!it->second.is<double>()) {
+				return ErrorResponse(400, "bad_request",
+					"connection field must be a non-negative integer");
+			}
+			const double v = it->second.get<double>();
+			if (v < 0 || v > max) {
+				return ErrorResponse(400, "bad_request",
+					"connection field out of range");
+			}
+			add_uint(connection, name, static_cast<std::uint32_t>(v));
+			any_conn = true;
+			CHttpServer::Response ok;
+			ok.status = 200;
+			return ok;
+		};
+		auto take_bool = [&](const char *key, ec_tagname_t name) -> CHttpServer::Response {
+			const auto it = connection_obj->find(key);
+			if (it == connection_obj->end()) {
+				CHttpServer::Response ok;
+				ok.status = 0;
+				return ok;
+			}
+			if (!it->second.is<bool>()) {
+				return ErrorResponse(400, "bad_request",
+					"connection field must be a bool");
+			}
+			add_bool(connection, name, it->second.get<bool>());
+			any_conn = true;
+			CHttpServer::Response ok;
+			ok.status = 200;
+			return ok;
+		};
+
+		// Uints — kbps caps in [0, 1_000_000_000], ports in [0, 65535].
+		const std::uint32_t kbps_max = 1000000000u;
+		auto r1 = take_uint("max_upload_kbps",       EC_TAG_CONN_MAX_UL,            kbps_max);
+		if (r1.status >= 400) return r1;
+		auto r2 = take_uint("max_download_kbps",     EC_TAG_CONN_MAX_DL,            kbps_max);
+		if (r2.status >= 400) return r2;
+		auto r3 = take_uint("max_upload_cap_kbps",   EC_TAG_CONN_UL_CAP,            kbps_max);
+		if (r3.status >= 400) return r3;
+		auto r4 = take_uint("max_download_cap_kbps", EC_TAG_CONN_DL_CAP,            kbps_max);
+		if (r4.status >= 400) return r4;
+		auto r5 = take_uint("slot_allocation",       EC_TAG_CONN_SLOT_ALLOCATION,   65535);
+		if (r5.status >= 400) return r5;
+		auto r6 = take_uint("tcp_port",              EC_TAG_CONN_TCP_PORT,          65535);
+		if (r6.status >= 400) return r6;
+		auto r7 = take_uint("udp_port",              EC_TAG_CONN_UDP_PORT,          65535);
+		if (r7.status >= 400) return r7;
+		auto r8 = take_uint("max_sources_per_file",  EC_TAG_CONN_MAX_FILE_SOURCES,  65535);
+		if (r8.status >= 400) return r8;
+		auto r9 = take_uint("max_connections",       EC_TAG_CONN_MAX_CONN,          65535);
+		if (r9.status >= 400) return r9;
+
+		// Bools.
+		auto rb1 = take_bool("udp_disabled",  EC_TAG_CONN_UDP_DISABLE);
+		if (rb1.status >= 400) return rb1;
+		auto rb2 = take_bool("autoconnect",   EC_TAG_CONN_AUTOCONNECT);
+		if (rb2.status >= 400) return rb2;
+		auto rb3 = take_bool("reconnect",     EC_TAG_CONN_RECONNECT);
+		if (rb3.status >= 400) return rb3;
+		auto rb4 = take_bool("network_ed2k",  EC_TAG_NETWORK_ED2K);
+		if (rb4.status >= 400) return rb4;
+		auto rb5 = take_bool("network_kad",   EC_TAG_NETWORK_KADEMLIA);
+		if (rb5.status >= 400) return rb5;
+
+		if (any_conn) {
+			ec_req->AddTag(connection);
+			any_change = true;
+		}
+	}
+
+	if (!any_change) {
+		return ErrorResponse(400, "bad_request",
+			"request body did not include any known pref fields");
+	}
+
+	const CECPacket *ec_resp = m_app.SendRecvSerialized(ec_req.get());
+	if (!ec_resp) {
+		return ErrorResponse(503, "ec_unavailable",
+			"EC roundtrip failed for SET_PREFERENCES");
+	}
+	std::string ec_err_msg;
+	if (IsEcFailedResponse(ec_resp, ec_err_msg)) {
+		delete ec_resp;
+		return ErrorResponse(400, "amuled_rejected", ec_err_msg.c_str());
+	}
+	delete ec_resp;
+
+	// Inline refresh — the GET below + the next /preferences must
+	// reflect the post-mutation state without waiting on the regular
+	// tick.
+	(void) RefresherTick(m_app, m_state);
+
+	// Return the updated /preferences shape so consumers can confirm
+	// what landed without a follow-up GET.
+	const webapi::PreferencesSnapshot p = m_state.Preferences();
+	CHttpServer::Response r;
+	r.status       = 200;
+	r.content_type = "application/json";
+	CJsonWriter w;
+	w.BeginObject();
+	  w.Key("general");
+	  w.BeginObject();
+	    w.Key("nickname");          w.ValueString(wxString::FromUTF8(p.nickname.c_str()));
+	    w.Key("user_hash");         w.ValueString(wxString::FromUTF8(p.user_hash.c_str()));
+	    w.Key("host_name");         w.ValueString(wxString::FromUTF8(p.host_name.c_str()));
+	    w.Key("check_new_version"); w.ValueBool(p.check_new_version);
+	  w.EndObject();
+	  w.Key("connection");
+	  w.BeginObject();
+	    w.Key("max_upload_kbps");       w.ValueInt(static_cast<int64_t>(p.max_upload_kbps));
+	    w.Key("max_download_kbps");     w.ValueInt(static_cast<int64_t>(p.max_download_kbps));
+	    w.Key("max_upload_cap_kbps");   w.ValueInt(static_cast<int64_t>(p.max_upload_cap_kbps));
+	    w.Key("max_download_cap_kbps"); w.ValueInt(static_cast<int64_t>(p.max_download_cap_kbps));
+	    w.Key("slot_allocation");       w.ValueInt(static_cast<int64_t>(p.slot_allocation));
+	    w.Key("tcp_port");              w.ValueInt(static_cast<int64_t>(p.tcp_port));
+	    w.Key("udp_port");              w.ValueInt(static_cast<int64_t>(p.udp_port));
+	    w.Key("udp_disabled");          w.ValueBool(p.udp_disabled);
+	    w.Key("max_sources_per_file");  w.ValueInt(static_cast<int64_t>(p.max_sources_per_file));
+	    w.Key("max_connections");       w.ValueInt(static_cast<int64_t>(p.max_connections));
+	    w.Key("autoconnect");           w.ValueBool(p.autoconnect);
+	    w.Key("reconnect");             w.ValueBool(p.reconnect);
+	    w.Key("network_ed2k");          w.ValueBool(p.network_ed2k);
+	    w.Key("network_kad");           w.ValueBool(p.network_kad);
+	  w.EndObject();
+	w.EndObject();
+	FinalizeJsonBody(w, r);
+	return r;
+}
+
+
+
+namespace {
+
+// Issue a single-shot mutation EC packet (no body), check the
+// response, run RefresherTick inline, return a standard
+// `{ok: true, message?: "..."}` response. Used by every connection-
+// control endpoint where the EC op is parameterless.
+CHttpServer::Response SimpleConnControlOp(
+	CamuleapiApp &app, webapi::CState &state,
+	ec_opcode_t op, unsigned http_status)
+{
+	std::unique_ptr<CECPacket> ec_req(new CECPacket(op));
+	const CECPacket *ec_resp = app.SendRecvSerialized(ec_req.get());
+	if (!ec_resp) {
+		return ErrorResponse(503, "ec_unavailable",
+			"EC roundtrip failed");
+	}
+	std::string ec_err_msg;
+	if (IsEcFailedResponse(ec_resp, ec_err_msg)) {
+		delete ec_resp;
+		return ErrorResponse(400, "amuled_rejected", ec_err_msg.c_str());
+	}
+	// amuled's CONNECT/DISCONNECT return EC_OP_STRINGS with a status
+	// message. We surface the message verbatim so consumers see what
+	// amuled would have shown in its UI.
+	std::string message;
+	if (ec_resp) {
+		for (CECPacket::const_iterator it = ec_resp->begin();
+		     it != ec_resp->end(); ++it) {
+			const CECTag *t = &*it;
+			if (t->GetTagName() == EC_TAG_STRING) {
+				if (!message.empty()) message += "; ";
+				message += std::string(t->GetStringData().utf8_str());
+			}
+		}
+	}
+	delete ec_resp;
+
+	(void) RefresherTick(app, state);
+
+	CHttpServer::Response r;
+	r.status       = http_status;
+	r.content_type = "application/json";
+	CJsonWriter w;
+	w.BeginObject();
+	  w.Key("ok");      w.ValueBool(true);
+	  if (!message.empty()) {
+		  w.Key("message"); w.ValueString(wxString::FromUTF8(message.c_str()));
+	  }
+	w.EndObject();
+	FinalizeJsonBody(w, r);
+	return r;
+}
+
+}  // namespace
+
+
+CHttpServer::Response CApiDispatcher::HandleNetworksConnect(
+	const CHttpServer::Request &req)
+{
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations, m_authRateLimiter,
+		kSessionCookieName);
+	if (!a.ok) return a.rejection;
+	if (auto rej = RequireAdmin(a)) return *rej;
+
+	// Optional `{"network": "ed2k" | "kad" | "both"}` selector — same
+	// shape as /networks/disconnect. Default "both" preserves the
+	// original parameterless contract (every connector-aware client
+	// kept working when this body was added).
+	std::string network = "both";
+	if (!req.body.empty()) {
+		picojson::value root;
+		std::string parse_err;
+		if (!ParseJsonObjectBody(req.body, root, parse_err)) {
+			return ErrorResponse(400, "bad_request", parse_err.c_str());
+		}
+		const auto &obj = root.get<picojson::object>();
+		const auto it = obj.find("network");
+		if (it != obj.end()) {
+			if (!it->second.is<std::string>()) {
+				return ErrorResponse(400, "bad_request",
+					"`network` must be one of \"ed2k\", \"kad\", \"both\"");
+			}
+			network = it->second.get<std::string>();
+			if (network != "ed2k" && network != "kad" && network != "both") {
+				return ErrorResponse(400, "bad_request",
+					"`network` must be one of \"ed2k\", \"kad\", \"both\"");
+			}
+		}
+	}
+
+	if (network == "ed2k") {
+		return SimpleConnControlOp(m_app, m_state,
+			EC_OP_SERVER_CONNECT, 202);
+	}
+	if (network == "kad") {
+		return SimpleConnControlOp(m_app, m_state,
+			EC_OP_KAD_START, 202);
+	}
+	return SimpleConnControlOp(m_app, m_state, EC_OP_CONNECT, 202);
+}
+
+
+CHttpServer::Response CApiDispatcher::HandleNetworksDisconnect(
+	const CHttpServer::Request &req)
+{
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations, m_authRateLimiter,
+		kSessionCookieName);
+	if (!a.ok) return a.rejection;
+	if (auto rej = RequireAdmin(a)) return *rej;
+
+	// Optional `{"network": "ed2k" | "kad" | "both"}` selector. Default
+	// "both" (preserves the original parameterless contract). Empty
+	// body is fine — that's the most common shape and matches the v0
+	// contract callers built against.
+	std::string network = "both";
+	if (!req.body.empty()) {
+		picojson::value root;
+		std::string parse_err;
+		if (!ParseJsonObjectBody(req.body, root, parse_err)) {
+			return ErrorResponse(400, "bad_request", parse_err.c_str());
+		}
+		const auto &obj = root.get<picojson::object>();
+		const auto it = obj.find("network");
+		if (it != obj.end()) {
+			if (!it->second.is<std::string>()) {
+				return ErrorResponse(400, "bad_request",
+					"`network` must be one of \"ed2k\", \"kad\", \"both\"");
+			}
+			network = it->second.get<std::string>();
+			if (network != "ed2k" && network != "kad" && network != "both") {
+				return ErrorResponse(400, "bad_request",
+					"`network` must be one of \"ed2k\", \"kad\", \"both\"");
+			}
+		}
+	}
+
+	if (network == "ed2k") {
+		return SimpleConnControlOp(m_app, m_state,
+			EC_OP_SERVER_DISCONNECT, 200);
+	}
+	if (network == "kad") {
+		return SimpleConnControlOp(m_app, m_state,
+			EC_OP_KAD_STOP, 200);
+	}
+	// "both": amuled's EC_OP_DISCONNECT short-circuits to both
+	// SERVER_DISCONNECT and KAD_STOP in one EC roundtrip.
+	return SimpleConnControlOp(m_app, m_state, EC_OP_DISCONNECT, 200);
+}
+
+
+// HandleKadConnect / HandleKadDisconnect were removed — strict
+// aliases of HandleNetworksConnect / HandleNetworksDisconnect with
+// `{"network":"kad"}`. The Kad bootstrap handler below is genuinely
+// distinct (single-contact bootstrap from an explicit IP+port) and
+// stays.
+
+CHttpServer::Response CApiDispatcher::HandleKadBootstrap(
+	const CHttpServer::Request &req)
+{
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations, m_authRateLimiter,
+		kSessionCookieName);
+	if (!a.ok) return a.rejection;
+	if (auto rej = RequireAdmin(a)) return *rej;
+
+	picojson::value root;
+	std::string parse_err;
+	if (!ParseJsonObjectBody(req.body, root, parse_err)) {
+		return ErrorResponse(400, "bad_request", parse_err.c_str());
+	}
+	const auto &obj = root.get<picojson::object>();
+
+	// Body: {"ip": "1.2.3.4" | <uint32 host-order>, "port": <uint16>}.
+	// Accept the IP either as a dotted-quad string (friendly) OR as
+	// a uint32 (matches the EC tag's wire shape directly).
+	std::uint32_t ip_he = 0;
+	{
+		const auto it = obj.find("ip");
+		if (it == obj.end()) {
+			return ErrorResponse(400, "bad_request",
+				"required field `ip` is missing");
+		}
+		if (it->second.is<std::string>()) {
+			// Dotted-quad string. Parse with strtoul on each octet.
+			const std::string &s = it->second.get<std::string>();
+			unsigned a_, b_, c_, d_;
+			if (std::sscanf(s.c_str(), "%u.%u.%u.%u",
+			                &a_, &b_, &c_, &d_) != 4
+			    || a_ > 255 || b_ > 255 || c_ > 255 || d_ > 255) {
+				return ErrorResponse(400, "bad_request",
+					"`ip` must be a dotted-quad IPv4 address or a "
+					"host-order uint32");
+			}
+			ip_he = (a_) | (b_ << 8) | (c_ << 16) | (d_ << 24);
+		} else if (it->second.is<double>()) {
+			const double v = it->second.get<double>();
+			if (v < 0 || v > 4294967295.0) {
+				return ErrorResponse(400, "bad_request",
+					"`ip` uint32 out of range");
+			}
+			ip_he = static_cast<std::uint32_t>(v);
+		} else {
+			return ErrorResponse(400, "bad_request",
+				"`ip` must be a string or number");
+		}
+	}
+	std::uint16_t port = 0;
+	{
+		const auto it = obj.find("port");
+		if (it == obj.end() || !it->second.is<double>()) {
+			return ErrorResponse(400, "bad_request",
+				"required numeric field `port` is missing");
+		}
+		const double v = it->second.get<double>();
+		if (v < 0 || v > 65535) {
+			return ErrorResponse(400, "bad_request",
+				"`port` must be in [0, 65535]");
+		}
+		port = static_cast<std::uint16_t>(v);
+	}
+
+	std::unique_ptr<CECPacket> ec_req(
+		new CECPacket(EC_OP_KAD_BOOTSTRAP_FROM_IP));
+	ec_req->AddTag(CECTag(EC_TAG_BOOTSTRAP_IP, ip_he));
+	ec_req->AddTag(CECTag(EC_TAG_BOOTSTRAP_PORT, port));
+
+	const CECPacket *ec_resp = m_app.SendRecvSerialized(ec_req.get());
+	if (!ec_resp) {
+		return ErrorResponse(503, "ec_unavailable",
+			"EC roundtrip failed for KAD_BOOTSTRAP_FROM_IP");
+	}
+	std::string ec_err_msg;
+	if (IsEcFailedResponse(ec_resp, ec_err_msg)) {
+		delete ec_resp;
+		return ErrorResponse(400, "amuled_rejected", ec_err_msg.c_str());
+	}
+	delete ec_resp;
+
+	(void) RefresherTick(m_app, m_state);
+
+	CHttpServer::Response r;
+	r.status       = 202;
+	r.content_type = "application/json";
+	CJsonWriter w;
+	w.BeginObject();
+	  w.Key("ok");   w.ValueBool(true);
+	  w.Key("ip");   w.ValueInt(static_cast<int64_t>(ip_he));
+	  w.Key("port"); w.ValueInt(static_cast<int64_t>(port));
+	w.EndObject();
+	FinalizeJsonBody(w, r);
+	return r;
+}
+
+
+
+namespace {
+
+// Inverse of SharedPriorityName in Refresher.cpp. Wire form mirrors
+// the /shared[].priority enum: bare priorities ("low", "normal",
+// "high", "release", "very_low", "auto") + their *_auto variants
+// (encoded by amule as `prio + 10`). Returns false on unknown enum.
+bool SharedPriorityToCode(const std::string &name, std::uint8_t &out)
+{
+	if      (name == "very_low")      { out = PR_VERY_LOW;                 return true; }
+	else if (name == "very_low_auto") { out = PR_VERY_LOW + 10;            return true; }
+	else if (name == "low")           { out = PR_LOW;                      return true; }
+	else if (name == "low_auto")      { out = PR_LOW + 10;                 return true; }
+	else if (name == "normal")        { out = PR_NORMAL;                   return true; }
+	else if (name == "normal_auto")   { out = PR_NORMAL + 10;              return true; }
+	else if (name == "high")          { out = PR_HIGH;                     return true; }
+	else if (name == "high_auto")     { out = PR_HIGH + 10;                return true; }
+	else if (name == "release")       { out = PR_VERYHIGH;                 return true; }
+	else if (name == "release_auto")  { out = PR_VERYHIGH + 10;            return true; }
+	else if (name == "auto")          { out = PR_AUTO;                     return true; }
+	return false;
+}
+
+}  // namespace
+
+
+CHttpServer::Response CApiDispatcher::HandleSharedPatch(
+	const CHttpServer::Request &req, const std::string &key)
+{
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations, m_authRateLimiter,
+		kSessionCookieName);
+	if (!a.ok) return a.rejection;
+	if (auto rej = RequireAdmin(a)) return *rej;
+
+	if (!m_state.HasFirstSnapshot()) {
+		return ErrorResponse(503, "ec_unavailable",
+			"amuleapi has not received its first EC snapshot yet");
+	}
+
+	webapi::FileSnapshot s;
+	std::string needle = key;
+	std::transform(needle.begin(), needle.end(), needle.begin(),
+		[](unsigned char c) { return std::tolower(c); });
+	if (!m_state.FindShared(needle, s)) {
+		return ErrorResponse(404, "not_found",
+			"no shared file with that hash");
+	}
+
+	picojson::value root;
+	std::string parse_err;
+	if (!ParseJsonObjectBody(req.body, root, parse_err)) {
+		return ErrorResponse(400, "bad_request", parse_err.c_str());
+	}
+	const auto &obj = root.get<picojson::object>();
+
+	const auto pit = obj.find("priority");
+	if (pit == obj.end()) {
+		return ErrorResponse(400, "bad_request",
+			"request body must include `priority`");
+	}
+	if (!pit->second.is<std::string>()) {
+		return ErrorResponse(400, "bad_request",
+			"`priority` must be a wire-string enum");
+	}
+	std::uint8_t code = 0;
+	if (!SharedPriorityToCode(pit->second.get<std::string>(), code)) {
+		return ErrorResponse(400, "bad_request",
+			"`priority` must be one of "
+			"very_low, low, normal, high, release, auto "
+			"(and their *_auto variants)");
+	}
+
+	CMD4Hash file_hash;
+	if (!HashFromHex(s.hash, file_hash)) {
+		return ErrorResponse(500, "internal_error",
+			"failed to decode file hash");
+	}
+	std::unique_ptr<CECPacket> ec_req(new CECPacket(EC_OP_SHARED_SET_PRIO));
+	CECTag hash_tag(EC_TAG_PARTFILE, file_hash);
+	hash_tag.AddTag(CECTag(EC_TAG_PARTFILE_PRIO, code));
+	ec_req->AddTag(hash_tag);
+
+	const CECPacket *ec_resp = m_app.SendRecvSerialized(ec_req.get());
+	if (!ec_resp) {
+		return ErrorResponse(503, "ec_unavailable",
+			"EC roundtrip failed for SHARED_SET_PRIO");
+	}
+	std::string ec_err_msg;
+	if (IsEcFailedResponse(ec_resp, ec_err_msg)) {
+		delete ec_resp;
+		return ErrorResponse(400, "amuled_rejected", ec_err_msg.c_str());
+	}
+	delete ec_resp;
+
+	(void) RefresherTick(m_app, m_state);
+
+	// Re-read post-mutation. Fall back to prior copy if evicted.
+	webapi::FileSnapshot s_after = s;
+	(void) m_state.FindShared(s.hash, s_after);
+
+	CHttpServer::Response r;
+	r.status       = 200;
+	r.content_type = "application/json";
+	CJsonWriter w;
+	WriteSharedObject(w, s_after);
+	FinalizeJsonBody(w, r);
+	return r;
+}
+
+
+CHttpServer::Response CApiDispatcher::HandleSharedReload(
+	const CHttpServer::Request &req)
+{
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations, m_authRateLimiter,
+		kSessionCookieName);
+	if (!a.ok) return a.rejection;
+	if (auto rej = RequireAdmin(a)) return *rej;
+	// EC_OP_SHAREDFILES_RELOAD: amuled re-walks every configured share
+	// root and re-publishes the contents. Synchronous on amuled's side
+	// but bounded by I/O over the share tree — typical small libraries
+	// complete in well under a second. Inline RefresherTick re-pulls
+	// the shared-files cache so SSE subscribers see `shared_added` /
+	// `_removed` events for the delta before the response lands.
+	return SimpleConnControlOp(m_app, m_state,
+		EC_OP_SHAREDFILES_RELOAD, 202);
+}
+
+
+
+namespace {
+
+// Parse a uint8 index from a URL capture. Categories are 0..255 (the
+// EC tag stores them as uint8). Returns false on overflow, negative,
+// or non-digit content.
+bool ParseCategoryIndex(const std::string &s, std::uint8_t &out)
+{
+	if (s.empty()) return false;
+	char *end = nullptr;
+	const unsigned long v = std::strtoul(s.c_str(), &end, 10);
+	if (end == s.c_str() || *end != '\0') return false;
+	if (v > 255) return false;
+	out = static_cast<std::uint8_t>(v);
+	return true;
+}
+
+
+// Inverse of CategoryPriorityName (Refresher.cpp's ParseCategoryTag).
+// Categories use the SAME priority enum as downloads, including the
+// `+10` auto-flag offset. Maps wire strings to PR_* codes.
+bool CategoryPriorityToCode(const std::string &name, std::uint8_t &out)
+{
+	if      (name == "very_low") { out = PR_VERY_LOW;       return true; }
+	else if (name == "low")      { out = PR_LOW;            return true; }
+	else if (name == "normal")   { out = PR_NORMAL;         return true; }
+	else if (name == "high")     { out = PR_HIGH;           return true; }
+	else if (name == "release")  { out = PR_VERYHIGH;       return true; }
+	else if (name == "auto")     { out = PR_AUTO;           return true; }
+	return false;
+}
+
+
+// Build the CEC_Category_Tag-shaped tag amuled expects. The shape is:
+//  parent tag EC_TAG_CATEGORY with the index as the int payload,
+//  nested children:
+//    EC_TAG_CATEGORY_TITLE   (string, "name" in our API)
+//    EC_TAG_CATEGORY_PATH    (string, "path")
+//    EC_TAG_CATEGORY_COMMENT (string, "comment")
+//    EC_TAG_CATEGORY_COLOR   (uint32)
+//    EC_TAG_CATEGORY_PRIO    (uint8)
+//
+// For CREATE the index is `0xFFFFFFFF` (sentinel: amuled assigns the
+// next free slot). For UPDATE we pass the actual index. For DELETE
+// the tag is just `(EC_TAG_CATEGORY, index)` — no children needed.
+CECTag BuildCategoryTag(std::uint32_t index,
+                        const std::string &name,
+                        const std::string &path,
+                        const std::string &comment,
+                        std::uint32_t color,
+                        std::uint8_t  prio)
+{
+	CECTag t(EC_TAG_CATEGORY, index);
+	t.AddTag(CECTag(EC_TAG_CATEGORY_TITLE,   wxString::FromUTF8(name.c_str())));
+	t.AddTag(CECTag(EC_TAG_CATEGORY_PATH,    wxString::FromUTF8(path.c_str())));
+	t.AddTag(CECTag(EC_TAG_CATEGORY_COMMENT, wxString::FromUTF8(comment.c_str())));
+	t.AddTag(CECTag(EC_TAG_CATEGORY_COLOR,   color));
+	t.AddTag(CECTag(EC_TAG_CATEGORY_PRIO,    prio));
+	return t;
+}
+
+
+// Helper to extract optional name/path/comment/color/priority from a
+// JSON object. Populates the out-params; returns an error response
+// on shape violations. The `is_create` flag enables required-field
+// enforcement: CREATE needs a name, UPDATE/PATCH treat all as
+// optional.
+struct CategoryFields {
+	std::string  name;
+	std::string  path;
+	std::string  comment;
+	std::uint32_t color = 0;
+	std::uint8_t  prio  = PR_NORMAL;
+	bool          has_name    = false;
+	bool          has_path    = false;
+	bool          has_comment = false;
+	bool          has_color   = false;
+	bool          has_prio    = false;
+};
+
+
+CHttpServer::Response ParseCategoryFields(const picojson::object &obj,
+                                          CategoryFields &out)
+{
+	auto get_string = [&obj](const char *key, std::string &dst,
+	                         bool &has) -> CHttpServer::Response {
+		const auto it = obj.find(key);
+		if (it == obj.end()) {
+			CHttpServer::Response ok; ok.status = 0; return ok;
+		}
+		if (!it->second.is<std::string>()) {
+			return ErrorResponse(400, "bad_request",
+				"category field must be a string");
+		}
+		dst = it->second.get<std::string>();
+		has = true;
+		CHttpServer::Response ok; ok.status = 200; return ok;
+	};
+
+	auto r1 = get_string("name",    out.name,    out.has_name);    if (r1.status >= 400) return r1;
+	auto r2 = get_string("path",    out.path,    out.has_path);    if (r2.status >= 400) return r2;
+	auto r3 = get_string("comment", out.comment, out.has_comment); if (r3.status >= 400) return r3;
+	{
+		const auto it = obj.find("color");
+		if (it != obj.end()) {
+			if (!it->second.is<double>()) {
+				return ErrorResponse(400, "bad_request",
+					"`color` must be a uint32");
+			}
+			const double v = it->second.get<double>();
+			if (v < 0 || v > 4294967295.0) {
+				return ErrorResponse(400, "bad_request",
+					"`color` out of range");
+			}
+			out.color = static_cast<std::uint32_t>(v);
+			out.has_color = true;
+		}
+	}
+	{
+		const auto it = obj.find("priority");
+		if (it != obj.end()) {
+			if (!it->second.is<std::string>()) {
+				return ErrorResponse(400, "bad_request",
+					"`priority` must be a wire-string enum");
+			}
+			if (!CategoryPriorityToCode(it->second.get<std::string>(),
+			                            out.prio)) {
+				return ErrorResponse(400, "bad_request",
+					"`priority` must be one of low, normal, high, "
+					"release, very_low, auto");
+			}
+			out.has_prio = true;
+		}
+	}
+	CHttpServer::Response ok; ok.status = 200; return ok;
+}
+
+}  // namespace
+
+
+CHttpServer::Response CApiDispatcher::HandleCategoryCreate(
+	const CHttpServer::Request &req)
+{
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations, m_authRateLimiter,
+		kSessionCookieName);
+	if (!a.ok) return a.rejection;
+	if (auto rej = RequireAdmin(a)) return *rej;
+
+	picojson::value root;
+	std::string parse_err;
+	if (!ParseJsonObjectBody(req.body, root, parse_err)) {
+		return ErrorResponse(400, "bad_request", parse_err.c_str());
+	}
+	const auto &obj = root.get<picojson::object>();
+
+	CategoryFields f;
+	auto err = ParseCategoryFields(obj, f);
+	if (err.status >= 400) return err;
+	if (!f.has_name || f.name.empty()) {
+		return ErrorResponse(400, "bad_request",
+			"required string field `name` is missing");
+	}
+
+	// CREATE: index sentinel is 0xFFFFFFFF — amuled assigns the next
+	// free slot and returns NOOP on success.
+	std::unique_ptr<CECPacket> ec_req(new CECPacket(EC_OP_CREATE_CATEGORY));
+	ec_req->AddTag(BuildCategoryTag(0xFFFFFFFFu, f.name, f.path,
+		f.comment, f.color, f.prio));
+
+	const CECPacket *ec_resp = m_app.SendRecvSerialized(ec_req.get());
+	if (!ec_resp) {
+		return ErrorResponse(503, "ec_unavailable",
+			"EC roundtrip failed for CREATE_CATEGORY");
+	}
+	std::string ec_err_msg;
+	if (IsEcFailedResponse(ec_resp, ec_err_msg)) {
+		delete ec_resp;
+		return ErrorResponse(400, "amuled_rejected", ec_err_msg.c_str());
+	}
+	delete ec_resp;
+
+	(void) RefresherTick(m_app, m_state);
+
+	// Look up the newly-created category by name to get its assigned
+	// index. (amuled's CREATE returns NOOP without the index; we have
+	// to scan the cache.) Fall back to 201 with no index if we can't
+	// find it — shouldn't happen but keeps the surface honest.
+	int created_index = -1;
+	for (const auto &c : m_state.Categories()) {
+		if (c.name == f.name) {
+			created_index = static_cast<int>(c.index);
+			break;
+		}
+	}
+
+	CHttpServer::Response r;
+	r.status       = 201;
+	r.content_type = "application/json";
+	CJsonWriter w;
+	w.BeginObject();
+	  w.Key("ok");    w.ValueBool(true);
+	  w.Key("name");  w.ValueString(wxString::FromUTF8(f.name.c_str()));
+	  if (created_index >= 0) {
+		  w.Key("index"); w.ValueInt(static_cast<int64_t>(created_index));
+	  }
+	w.EndObject();
+	FinalizeJsonBody(w, r);
+	return r;
+}
+
+
+CHttpServer::Response CApiDispatcher::HandleCategoryUpdate(
+	const CHttpServer::Request &req, const std::string &index_str)
+{
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations, m_authRateLimiter,
+		kSessionCookieName);
+	if (!a.ok) return a.rejection;
+	if (auto rej = RequireAdmin(a)) return *rej;
+
+	std::uint8_t idx = 0;
+	if (!ParseCategoryIndex(index_str, idx)) {
+		return ErrorResponse(400, "bad_request",
+			"path `{index}` must be a uint8 in [0, 255]");
+	}
+	if (!m_state.HasFirstSnapshot()) {
+		return ErrorResponse(503, "ec_unavailable",
+			"amuleapi has not received its first EC snapshot yet");
+	}
+
+	// Find the existing category — we need its current values for any
+	// field the PATCH body doesn't override (CEC_Category_Tag is
+	// not delta-friendly; we always send the full tag).
+	webapi::CategorySnapshot current;
+	bool found = false;
+	for (const auto &c : m_state.Categories()) {
+		if (static_cast<std::uint8_t>(c.index) == idx) {
+			current = c;
+			found = true;
+			break;
+		}
+	}
+	if (!found) {
+		return ErrorResponse(404, "not_found",
+			"no category with that index");
+	}
+
+	picojson::value root;
+	std::string parse_err;
+	if (!ParseJsonObjectBody(req.body, root, parse_err)) {
+		return ErrorResponse(400, "bad_request", parse_err.c_str());
+	}
+	const auto &obj = root.get<picojson::object>();
+
+	CategoryFields f;
+	auto err = ParseCategoryFields(obj, f);
+	if (err.status >= 400) return err;
+
+	const std::string name    = f.has_name    ? f.name    : current.name;
+	const std::string path    = f.has_path    ? f.path    : current.path;
+	const std::string comment = f.has_comment ? f.comment : current.comment;
+	const std::uint32_t color = f.has_color   ? f.color   : current.color;
+	const std::uint8_t  prio  = f.has_prio    ? f.prio    : current.priority_code;
+
+	std::unique_ptr<CECPacket> ec_req(new CECPacket(EC_OP_UPDATE_CATEGORY));
+	ec_req->AddTag(BuildCategoryTag(idx, name, path, comment, color, prio));
+
+	const CECPacket *ec_resp = m_app.SendRecvSerialized(ec_req.get());
+	if (!ec_resp) {
+		return ErrorResponse(503, "ec_unavailable",
+			"EC roundtrip failed for UPDATE_CATEGORY");
+	}
+	std::string ec_err_msg;
+	if (IsEcFailedResponse(ec_resp, ec_err_msg)) {
+		delete ec_resp;
+		return ErrorResponse(400, "amuled_rejected", ec_err_msg.c_str());
+	}
+	delete ec_resp;
+
+	(void) RefresherTick(m_app, m_state);
+
+	// Return the post-mutation category object.
+	webapi::CategorySnapshot after = current;
+	for (const auto &c : m_state.Categories()) {
+		if (static_cast<std::uint8_t>(c.index) == idx) {
+			after = c;
+			break;
+		}
+	}
+
+	CHttpServer::Response r;
+	r.status       = 200;
+	r.content_type = "application/json";
+	CJsonWriter w;
+	WriteCategoryObject(w, after);
+	FinalizeJsonBody(w, r);
+	return r;
+}
+
+
+CHttpServer::Response CApiDispatcher::HandleCategoryDelete(
+	const CHttpServer::Request &req, const std::string &index_str)
+{
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations, m_authRateLimiter,
+		kSessionCookieName);
+	if (!a.ok) return a.rejection;
+	if (auto rej = RequireAdmin(a)) return *rej;
+
+	std::uint8_t idx = 0;
+	if (!ParseCategoryIndex(index_str, idx)) {
+		return ErrorResponse(400, "bad_request",
+			"path `{index}` must be a uint8 in [0, 255]");
+	}
+	if (!m_state.HasFirstSnapshot()) {
+		return ErrorResponse(503, "ec_unavailable",
+			"amuleapi has not received its first EC snapshot yet");
+	}
+	// Index 0 is the implicit "All" category — amuled treats deleting
+	// it as illegal. Reject before the EC roundtrip.
+	if (idx == 0) {
+		return ErrorResponse(400, "bad_request",
+			"cannot delete the default (index=0) category");
+	}
+	bool found = false;
+	for (const auto &c : m_state.Categories()) {
+		if (static_cast<std::uint8_t>(c.index) == idx) { found = true; break; }
+	}
+	if (!found) {
+		return ErrorResponse(404, "not_found",
+			"no category with that index");
+	}
+
+	// CEC_Category_Tag CMD-detail shape: just `(EC_TAG_CATEGORY, idx)`,
+	// no children (amule-remote-gui.cpp:1043 uses `CEC_Category_Tag(cat,
+	// EC_DETAIL_CMD)`). We replicate that with a bare CECTag.
+	std::unique_ptr<CECPacket> ec_req(new CECPacket(EC_OP_DELETE_CATEGORY));
+	ec_req->AddTag(CECTag(EC_TAG_CATEGORY,
+		static_cast<std::uint32_t>(idx)));
+
+	const CECPacket *ec_resp = m_app.SendRecvSerialized(ec_req.get());
+	if (!ec_resp) {
+		return ErrorResponse(503, "ec_unavailable",
+			"EC roundtrip failed for DELETE_CATEGORY");
+	}
+	std::string ec_err_msg;
+	if (IsEcFailedResponse(ec_resp, ec_err_msg)) {
+		delete ec_resp;
+		return ErrorResponse(400, "amuled_rejected", ec_err_msg.c_str());
+	}
+	delete ec_resp;
+
+	(void) RefresherTick(m_app, m_state);
+
+	CHttpServer::Response r;
+	r.status       = 200;
+	r.content_type = "application/json";
+	CJsonWriter w;
+	w.BeginObject();
+	  w.Key("ok");    w.ValueBool(true);
+	  w.Key("index"); w.ValueInt(static_cast<int64_t>(idx));
+	w.EndObject();
+	FinalizeJsonBody(w, r);
+	return r;
+}
+
+
+
+namespace {
+
+// Map wire-string search types to amule's EC_SEARCH_TYPE enum.
+// "local" / "global" / "kad" matches amulegui's UI labels +
+// amule-remote-gui.cpp:2406-2410's switch.
+bool SearchTypeFromString(const std::string &s, std::uint8_t &out)
+{
+	if      (s == "local")  { out = EC_SEARCH_LOCAL;  return true; }
+	else if (s == "global") { out = EC_SEARCH_GLOBAL; return true; }
+	else if (s == "kad")    { out = EC_SEARCH_KAD;    return true; }
+	return false;
+}
+
+}  // namespace
+
+
+CHttpServer::Response CApiDispatcher::HandleSearchStart(
+	const CHttpServer::Request &req)
+{
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations, m_authRateLimiter,
+		kSessionCookieName);
+	if (!a.ok) return a.rejection;
+	if (auto rej = RequireAdmin(a)) return *rej;
+
+	picojson::value root;
+	std::string parse_err;
+	if (!ParseJsonObjectBody(req.body, root, parse_err)) {
+		return ErrorResponse(400, "bad_request", parse_err.c_str());
+	}
+	const auto &obj = root.get<picojson::object>();
+
+	// Body shape:
+	//  { "query": "...", required string
+	//    "type":  "local" | "global" | "kad" (default "global"),
+	//    "file_type":  string (optional, amule file-type label),
+	//    "extension":  string (optional, e.g. "mkv"),
+	//    "min_size":   uint64 bytes (optional, default 0),
+	//    "max_size":   uint64 bytes (optional, default 0 = no cap),
+	//    "min_avail":  uint32 (optional, default 0) }
+	std::string query;
+	{
+		const auto it = obj.find("query");
+		if (it == obj.end() || !it->second.is<std::string>()) {
+			return ErrorResponse(400, "bad_request",
+				"required string field `query` is missing");
+		}
+		query = it->second.get<std::string>();
+		if (query.empty()) {
+			return ErrorResponse(400, "bad_request",
+				"`query` must be non-empty");
+		}
+	}
+
+	std::uint8_t search_type = EC_SEARCH_GLOBAL;
+	std::string  search_kind = "global";  // mirrors the input string for state.MarkSearchStarted
+	{
+		const auto it = obj.find("type");
+		if (it != obj.end()) {
+			if (!it->second.is<std::string>()) {
+				return ErrorResponse(400, "bad_request",
+					"`type` must be one of \"local\", \"global\", \"kad\"");
+			}
+			search_kind = it->second.get<std::string>();
+			if (!SearchTypeFromString(search_kind, search_type)) {
+				return ErrorResponse(400, "bad_request",
+					"`type` must be one of \"local\", \"global\", \"kad\"");
+			}
+		}
+	}
+
+	std::string file_type;
+	{
+		const auto it = obj.find("file_type");
+		if (it != obj.end()) {
+			if (!it->second.is<std::string>()) {
+				return ErrorResponse(400, "bad_request",
+					"`file_type` must be a string");
+			}
+			file_type = it->second.get<std::string>();
+		}
+	}
+	std::string extension;
+	{
+		const auto it = obj.find("extension");
+		if (it != obj.end()) {
+			if (!it->second.is<std::string>()) {
+				return ErrorResponse(400, "bad_request",
+					"`extension` must be a string");
+			}
+			extension = it->second.get<std::string>();
+		}
+	}
+	std::uint64_t min_size = 0;
+	std::uint64_t max_size = 0;
+	std::uint32_t min_avail = 0;
+	{
+		const auto it = obj.find("min_size");
+		if (it != obj.end()) {
+			if (!it->second.is<double>()) {
+				return ErrorResponse(400, "bad_request",
+					"`min_size` must be a non-negative integer (bytes)");
+			}
+			const double v = it->second.get<double>();
+			if (v < 0) return ErrorResponse(400, "bad_request",
+				"`min_size` must be >= 0");
+			min_size = static_cast<std::uint64_t>(v);
+		}
+	}
+	{
+		const auto it = obj.find("max_size");
+		if (it != obj.end()) {
+			if (!it->second.is<double>()) {
+				return ErrorResponse(400, "bad_request",
+					"`max_size` must be a non-negative integer (bytes; 0 = no cap)");
+			}
+			const double v = it->second.get<double>();
+			if (v < 0) return ErrorResponse(400, "bad_request",
+				"`max_size` must be >= 0");
+			max_size = static_cast<std::uint64_t>(v);
+		}
+	}
+	{
+		const auto it = obj.find("min_avail");
+		if (it != obj.end()) {
+			if (!it->second.is<double>()) {
+				return ErrorResponse(400, "bad_request",
+					"`min_avail` must be a non-negative integer");
+			}
+			const double v = it->second.get<double>();
+			if (v < 0 || v > 4294967295.0) {
+				return ErrorResponse(400, "bad_request",
+					"`min_avail` out of range");
+			}
+			min_avail = static_cast<std::uint32_t>(v);
+		}
+	}
+
+	std::unique_ptr<CECPacket> ec_req(new CECPacket(EC_OP_SEARCH_START));
+	ec_req->AddTag(CEC_Search_Tag(
+		wxString::FromUTF8(query.c_str()),
+		static_cast<EC_SEARCH_TYPE>(search_type),
+		wxString::FromUTF8(file_type.c_str()),
+		wxString::FromUTF8(extension.c_str()),
+		min_avail,
+		min_size,
+		max_size));
+
+	const CECPacket *ec_resp = m_app.SendRecvSerialized(ec_req.get());
+	if (!ec_resp) {
+		return ErrorResponse(503, "ec_unavailable",
+			"EC roundtrip failed for SEARCH_START");
+	}
+	std::string ec_err_msg;
+	if (IsEcFailedResponse(ec_resp, ec_err_msg)) {
+		delete ec_resp;
+		return ErrorResponse(400, "amuled_rejected", ec_err_msg.c_str());
+	}
+	delete ec_resp;
+
+	// Hand the lifecycle off to the refresher: it wipes the results
+	// cache, marks active=true, captures the kind, and starts polling
+	// EC_OP_SEARCH_RESULTS + _PROGRESS every tick until the state
+	// machine in RefresherTick infers completion. Drops the prior
+	// per-GET TtlCache fetch (the refresher is the single fetcher
+	// now — needed so SSE search_result_added / search_progress fire
+	// on the same delta the polling consumer would observe).
+	m_state.MarkSearchStarted(search_kind);
+
+	CHttpServer::Response r;
+	r.status       = 202;
+	r.content_type = "application/json";
+	CJsonWriter w;
+	w.BeginObject();
+	  w.Key("ok");    w.ValueBool(true);
+	  w.Key("query"); w.ValueString(wxString::FromUTF8(query.c_str()));
+	w.EndObject();
+	FinalizeJsonBody(w, r);
+	return r;
+}
+
+
+CHttpServer::Response CApiDispatcher::HandleSearchStop(
+	const CHttpServer::Request &req)
+{
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations, m_authRateLimiter,
+		kSessionCookieName);
+	if (!a.ok) return a.rejection;
+	if (auto rej = RequireAdmin(a)) return *rej;
+
+	std::unique_ptr<CECPacket> ec_req(new CECPacket(EC_OP_SEARCH_STOP));
+	const CECPacket *ec_resp = m_app.SendRecvSerialized(ec_req.get());
+	if (!ec_resp) {
+		return ErrorResponse(503, "ec_unavailable",
+			"EC roundtrip failed for SEARCH_STOP");
+	}
+	std::string ec_err_msg;
+	if (IsEcFailedResponse(ec_resp, ec_err_msg)) {
+		delete ec_resp;
+		return ErrorResponse(400, "amuled_rejected", ec_err_msg.c_str());
+	}
+	delete ec_resp;
+
+	// /search/results stays valid after stop — amuled keeps the
+	// accumulated results until the next SEARCH_START. No cache
+	// invalidation needed; consumers polling /search/results see
+	// the same set they were just looking at.
+
+	CHttpServer::Response r;
+	r.status       = 200;
+	r.content_type = "application/json";
+	CJsonWriter w;
+	w.BeginObject();
+	  w.Key("ok"); w.ValueBool(true);
+	w.EndObject();
+	FinalizeJsonBody(w, r);
+	return r;
+}
+
+
+CHttpServer::Response CApiDispatcher::HandleSearchDownload(
+	const CHttpServer::Request &req, const std::string &hash)
+{
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations, m_authRateLimiter,
+		kSessionCookieName);
+	if (!a.ok) return a.rejection;
+	if (auto rej = RequireAdmin(a)) return *rej;
+
+	// Canonicalise the URL hash to lowercase.
+	std::string needle = hash;
+	std::transform(needle.begin(), needle.end(), needle.begin(),
+		[](unsigned char c) { return std::tolower(c); });
+
+	CMD4Hash file_hash;
+	if (!HashFromHex(needle, file_hash)) {
+		return ErrorResponse(400, "bad_request",
+			"`{hash}` must be a 32-char hex MD4");
+	}
+
+	// Optional body: {"category": uint8}. amulegui's
+	// CDownQueueRem::AddSearchToDownload defaults to category 0
+	// when none is supplied; we mirror that. The body itself is
+	// optional — clients that don't care about category POST with
+	// no body and get the default download path.
+	std::uint8_t category = 0;
+	if (!req.body.empty()) {
+		picojson::value root;
+		std::string parse_err;
+		if (!ParseJsonObjectBody(req.body, root, parse_err)) {
+			return ErrorResponse(400, "bad_request", parse_err.c_str());
+		}
+		const auto &obj = root.get<picojson::object>();
+		const auto it = obj.find("category");
+		if (it != obj.end()) {
+			if (!it->second.is<double>()) {
+				return ErrorResponse(400, "bad_request",
+					"`category` must be a non-negative integer");
+			}
+			const double v = it->second.get<double>();
+			if (v < 0 || v > 255) {
+				return ErrorResponse(400, "bad_request",
+					"`category` must be in [0, 255]");
+			}
+			category = static_cast<std::uint8_t>(v);
+		}
+	}
+
+	// amuled accepts the result hash as the partfile-tag's int
+	// payload (matches amule-remote-gui.cpp:2230). amuled looks up
+	// the hash in its searchlist; if not present, returns FAILED.
+	std::unique_ptr<CECPacket> ec_req(new CECPacket(EC_OP_DOWNLOAD_SEARCH_RESULT));
+	CECTag hash_tag(EC_TAG_PARTFILE, file_hash);
+	hash_tag.AddTag(CECTag(EC_TAG_PARTFILE_CAT, category));
+	ec_req->AddTag(hash_tag);
+
+	const CECPacket *ec_resp = m_app.SendRecvSerialized(ec_req.get());
+	if (!ec_resp) {
+		return ErrorResponse(503, "ec_unavailable",
+			"EC roundtrip failed for DOWNLOAD_SEARCH_RESULT");
+	}
+	std::string ec_err_msg;
+	if (IsEcFailedResponse(ec_resp, ec_err_msg)) {
+		delete ec_resp;
+		return ErrorResponse(400, "amuled_rejected", ec_err_msg.c_str());
+	}
+	delete ec_resp;
+
+	// Inline refresh so /downloads sees the new partfile (subject
+	// to amuled's async allocate-and-hash; same caveat as POST
+	// /downloads — the partfile surfaces within 1-2 ticks).
+	(void) RefresherTick(m_app, m_state);
+
+	CHttpServer::Response r;
+	r.status       = 202;
+	r.content_type = "application/json";
+	CJsonWriter w;
+	w.BeginObject();
+	  w.Key("ok");       w.ValueBool(true);
+	  w.Key("hash");     w.ValueString(wxString::FromUTF8(needle.c_str()));
+	  w.Key("category"); w.ValueInt(static_cast<int64_t>(category));
+	w.EndObject();
+	FinalizeJsonBody(w, r);
+	return r;
+}
+
+
+// SSE runs on a worker thread the HTTP server spawns per connection.
+// Auth is enforced in PreflightEvents (synchronous, before head
+// write and worker spawn); failures use the regular JSON error
+// envelope. The 15 s heartbeat is a `: keepalive\n\n` SSE comment
+// (RFC 6202) — proxies and many browsers drop idle TCP after ~30 s.
+//
+// DispatchStreaming reads head out-params ONCE before writing, so
+// one function here sets the head AND runs the drain loop.
+boost::optional<CHttpServer::Response> CApiDispatcher::PreflightEvents(
+	const CHttpServer::Request &req)
+{
+	// Same bearer/cookie check the live handler used to do, but run
+	// on the I/O thread BEFORE a worker thread is spawned and BEFORE
+	// the 32-slot SSE budget is touched. Unauth/locked-out peers
+	// get a normal request/response 401/429 and never reach the
+	// streaming path; the slot stays free for legitimate
+	// subscribers.
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations,
+		m_authRateLimiter, kSessionCookieName);
+	if (!a.ok) {
+		return a.rejection;
+	}
+	return boost::none;
+}
+
+
+void CApiDispatcher::DispatchEvents(
+	const CHttpServer::Request &req,
+	CHttpServer::Writer &writer,
+	unsigned &http_status,
+	std::string &content_type,
+	std::map<std::string, std::string> &response_headers)
+{
+	// Auth ran inside PreflightEvents on the I/O thread before this
+	// worker spawned, so we can assume an authenticated principal
+	// here. Re-running Verify on the worker thread would just burn
+	// one HMAC compare per connection for no security gain.
+	auto a = AuthenticateRequestRateLimited(req, m_jwt, m_revocations, m_authRateLimiter,
+		kSessionCookieName);
+	if (!a.ok) {
+		// Defence in depth — if PreflightEvents was bypassed for any
+		// reason (test harness, future routing change) we still
+		// reject here, just not as cheaply.
+		http_status = a.rejection.status;
+		content_type = "application/json";
+		writer.Write(a.rejection.body);
+		return;
+	}
+	// SSE doesn't need admin role — reads are guest-friendly. The
+	// channel multiplexes every event type clients want to subscribe
+	// to. Admin-gated mutations don't ship over SSE; SSE is a read-
+	// only push.
+
+	http_status   = 200;
+	content_type  = "text/event-stream";
+	response_headers["Cache-Control"]    = "no-cache";
+	response_headers["X-Accel-Buffering"] = "no";  // disable nginx buffering
+
+	// CORS on the SSE response too. EventSource sends
+	// `Origin` and reads only the standard CORS bundle for credentialed
+	// cross-origin streams. No Expose-Headers needed (SSE clients don't
+	// read response headers programmatically).
+	{
+		const std::string cors_org = ResolveCorsOrigin(req, m_config);
+		ApplyCorsHeaders(response_headers, cors_org,
+			m_config.ServerCfg().allow_cors);
+	}
+	// Also disable Connection: keep-alive override — chunked +
+	// streaming requires the default. (HttpServer adds chunked
+	// transfer-encoding automatically.)
+
+	// Initial reassurance chunk so the client knows the channel is
+	// open. Some browser EventSource impls don't fire `onopen` until
+	// at least one chunk lands.
+	if (!writer.Write(": connected\n\n")) return;
+
+	// Optional `?channels=<csv>` query: limit the event types
+	// delivered to a comma-separated subset. The mapping from
+	// EventBus event name → channel is prefix-based:
+	//  download_*  → "downloads"
+	//  shared_*    → "shared"
+	//  server_*    → "servers"
+	//  client_*    → "clients"
+	//  status_*    → "status"
+	//  log_*       → "logs"
+	// The synthetic per-subscriber `resync` event is ALWAYS
+	// delivered regardless of filter — its purpose is to signal a
+	// cache invalidation the client cannot opt out of.
+	// Unknown channel names in the query are silently ignored (allow
+	// forward-compatibility with future event families).
+	std::set<std::string> channel_filter;
+	bool channels_set = false;
+	{
+		// Cap unique channel tokens at 32 (six today + headroom)
+		// so a 1 MB `channels=` query can't build a 1M-entry set in
+		// the SSE worker.
+		constexpr std::size_t kMaxChannelTokens = 32;
+		std::string query;
+		const std::size_t q = req.target.find('?');
+		if (q != std::string::npos) query = req.target.substr(q + 1);
+		const auto qmap = web_api_path::ParseQuery(query);
+		const auto it = qmap.find("channels");
+		if (it != qmap.end() && !it->second.empty()) {
+			channels_set = true;
+			std::string cur;
+			bool overflowed = false;
+			auto insert_token = [&](std::string &&s) {
+				if (channel_filter.size() >= kMaxChannelTokens) {
+					overflowed = true;
+					return;
+				}
+				channel_filter.insert(std::move(s));
+			};
+			for (char c : it->second) {
+				if (c == ',') {
+					if (!cur.empty()) insert_token(std::move(cur));
+					cur.clear();
+					if (overflowed) break;
+				} else {
+					cur.push_back(c);
+				}
+			}
+			if (!overflowed && !cur.empty()) insert_token(std::move(cur));
+		}
+	}
+	auto event_channel = [](const std::string &name) -> std::string {
+		// Event naming convention: every bus event MUST contain at
+		// least one underscore — the prefix before the first `_`
+		// identifies the channel. The only no-underscore name on
+		// the wire is `resync`, which bypasses this filter entirely
+		// (synthetic per-subscriber, never via EventBus::Publish).
+		// Future bare-token events need explicit channel mapping or
+		// must always bypass like `resync`.
+		const auto us = name.find('_');
+		if (us == std::string::npos) return name;
+		const std::string prefix = name.substr(0, us);
+		if (prefix == "download") return "downloads";
+		if (prefix == "shared")   return "shared";
+		if (prefix == "server")   return "servers";
+		if (prefix == "client")   return "clients";
+		if (prefix == "status")   return "status";
+		if (prefix == "log")      return "logs";
+		if (prefix == "search")   return "search";
+		return prefix;
+	};
+	auto event_passes_filter = [&](const std::string &name) {
+		if (!channels_set) return true;
+		return channel_filter.count(event_channel(name)) > 0;
+	};
+
+	// Drain blocks up to the heartbeat interval (15 s); on timeout we
+	// emit `: keepalive` so the connection stays warm.
+	//
+	// `since_id` resolution per RFC 6202 §4 reconnect:
+	//  - absent / unparseable → start from NewestId (events fired
+	//    AFTER connect only)
+	//  - in-range (parsed+1 >= OldestId) → resume from `parsed`; the
+	//    first Drain returns the missed range immediately
+	//  - gap (parsed+1 < OldestId) → events evicted before this
+	//    client read them; emit `resync` (reason=gap) so the client
+	//    invalidates + re-GETs REST collections, then start from
+	//    NewestId
+	//  - parsed > NewestId → stale id from a prior daemon process
+	//    (ids reset to 1 on restart); emit `resync` (reason=restart)
+	//    and start from NewestId.
+	std::uint64_t since_id;
+	const std::string lei = FindHeaderCaseInsensitive(req.headers,
+		"Last-Event-ID");
+	const std::uint64_t newest = m_app.EventBus().NewestId();
+	const std::uint64_t oldest = m_app.EventBus().OldestId();
+	if (lei.empty()) {
+		since_id = newest;
+	} else {
+		char *end = nullptr;
+		const unsigned long long parsed = std::strtoull(lei.c_str(),
+			&end, 10);
+		if (end == lei.c_str() || *end != '\0') {
+			since_id = newest;
+		} else if (parsed > newest) {
+			// Per-subscriber synthetic event — not on the bus. id is
+			// the current newest so the client's EventSource resumes
+			// from there on the next reconnect (no resync loop).
+			std::ostringstream frame;
+			frame << "event: resync\n"
+			      << "id: "    << newest << "\n"
+			      << "data: {\"reason\":\"restart\",\"since_id\":"
+			      << static_cast<std::uint64_t>(parsed)
+			      << ",\"newest_id\":" << newest << "}\n\n";
+			if (!writer.Write(frame.str())) return;
+			since_id = newest;
+		} else if (oldest == 0 || parsed + 1 >= oldest) {
+			since_id = static_cast<std::uint64_t>(parsed);
+		} else {
+			std::ostringstream frame;
+			frame << "event: resync\n"
+			      << "id: "    << newest << "\n"
+			      << "data: {\"reason\":\"gap\",\"since_id\":"
+			      << static_cast<std::uint64_t>(parsed)
+			      << ",\"newest_id\":" << newest << "}\n\n";
+			if (!writer.Write(frame.str())) return;
+			since_id = newest;
+		}
+	}
+	// Heartbeat is wall-clock driven, not Drain-timeout driven —
+	// a busy bus + `?channels=` that filters every drained event
+	// would otherwise leave the wire silent (Drain returns
+	// immediately, loop swallows + re-enters, keepalive never
+	// fires). NAT/proxies/EventSource clients drop idle TCP after
+	// ~30–60 s, so emit `: keepalive` whenever last-write falls
+	// behind the 15 s budget.
+	const auto heartbeat_interval = std::chrono::seconds(15);
+	auto last_write_at = std::chrono::steady_clock::now();
+	std::vector<webapi::Event> drained;
+	while (writer.Alive()) {
+		// Shutdown poll. The Shutdown() flag is set by the App on
+		// OnExit, and Drain() returns immediately when it's
+		// observed. If the daemon is going down, drop this client
+		// cleanly so the dispatcher reset() doesn't race a worker
+		// still holding `m_app` references.
+		if (m_app.EventBus().IsShutdown()) break;
+		drained.clear();
+		const std::uint64_t new_high = m_app.EventBus().Drain(
+			since_id, heartbeat_interval, drained);
+		if (!writer.Alive()) break;
+		if (m_app.EventBus().IsShutdown()) break;
+
+		// Live-path gap detection. Reconnect handler above only
+		// catches gaps at session start; once running, a burst that
+		// fills + evicts the ring between Drains would silently drop
+		// the missed range. Check OldestId after each Drain — on
+		// cursor fall-off emit a typed resync and restart at newest.
+		const std::uint64_t oldest_now = m_app.EventBus().OldestId();
+		const std::uint64_t newest_now = m_app.EventBus().NewestId();
+		if (oldest_now > 0 && since_id + 1 < oldest_now) {
+			std::ostringstream gap_frame;
+			gap_frame << "event: resync\n"
+			          << "id: "    << newest_now << "\n"
+			          << "data: {\"reason\":\"gap\",\"since_id\":"
+			          << since_id
+			          << ",\"newest_id\":" << newest_now << "}\n\n";
+			if (!writer.Write(gap_frame.str())) break;
+			last_write_at = std::chrono::steady_clock::now();
+			since_id = newest_now;
+			// Drop the events the Drain returned — the client is
+			// about to re-fetch the REST collections (that's the
+			// `resync` contract) so any partial pre-resync events
+			// would be confusing noise.
+			continue;
+		}
+
+		// Apply ?channels= filter before emission. We still advance
+		// since_id over EVERY drained event (filtered or not) so the
+		// client doesn't re-see them on reconnect; reconnect replay is
+		// id-based, not channel-based.
+		std::ostringstream frame;
+		bool wrote_any = false;
+		for (const auto &ev : drained) {
+			if (!event_passes_filter(ev.name)) continue;
+			// SSE frame:  event: <name>\nid: <id>\ndata: <data>\n\n
+			// Per RFC 6202 §4 `data:` lines are single-line; our JSON
+			// payloads never contain literal newlines (EventDiff
+			// escapes them), so one `data:` line per event suffices.
+			//
+			// `ev.name` is NOT escaped — every event name on the bus
+			// is a server-controlled compile-time literal. A future
+			// publisher taking a name from external input MUST
+			// sanitize CR/LF/`\0` at its call site.
+			frame << "event: " << ev.name << "\n"
+			      << "id: "    << ev.id   << "\n"
+			      << "data: "  << ev.data << "\n\n";
+			wrote_any = true;
+		}
+		if (wrote_any) {
+			if (!writer.Write(frame.str())) break;
+			last_write_at = std::chrono::steady_clock::now();
+			since_id = new_high;
+		} else {
+			if (!drained.empty()) {
+				// Every drained event got filtered out — advance the
+				// cursor silently so the next Drain doesn't re-read
+				// them.
+				since_id = new_high;
+			}
+			// drained.empty() (Drain hit its timeout with nothing
+			// new) OR all-events-filtered-out (the channel-filter
+			// drop). In either case, emit a heartbeat IFF we
+			// haven't written anything in the heartbeat window.
+			const auto now = std::chrono::steady_clock::now();
+			if (now - last_write_at >= heartbeat_interval) {
+				if (!writer.Write(": keepalive\n\n")) break;
+				last_write_at = now;
+			}
+		}
+	}
+}
diff --git a/src/webapi/Api.h b/src/webapi/Api.h
new file mode 100644
index 0000000000..96bc752f0e
--- /dev/null
+++ b/src/webapi/Api.h
@@ -0,0 +1,259 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#ifndef WEBAPI_API_H
+#define WEBAPI_API_H
+
+#include <memory>
+#include <string>
+
+#include "Auth.h"
+#include "HttpServer.h"
+#include "State.h"        // ServerInfoLog / StatsTreeNode / StatsGraphs / SearchResult
+#include "TtlCache.h"
+
+#include <ctime>
+#include <map>
+#include <utility>
+
+
+class CAmuleApiConfig;
+class CamuleapiApp;
+class CJwt;
+
+namespace webapi { class CState; }
+
+
+// Request dispatcher for the `/api/v0/*` surface. Lives between the
+// transport (CHttpServer) and the per-endpoint handlers. Owns the
+// CJwt instance, the revocation set, and the rate limiter.
+//
+// References (not copies) of the config + jwt machinery: the App
+// constructs them once at startup and outlives every Request.
+// CRevocationSet + CRateLimiter live by-value inside the dispatcher
+// because they're amuleapi-owned state with no external consumer.
+
+class CApiDispatcher {
+public:
+	CApiDispatcher(const CAmuleApiConfig &config,
+	               CJwt                  &jwt,
+	               webapi::CState        &state,
+	               CamuleapiApp          &app);
+
+	CHttpServer::Response Dispatch(const CHttpServer::Request &req);
+
+	// streaming entry point. Called by HttpServer when the
+	// streaming_resolver matches `/api/v0/events`. The handler runs
+	// the SSE loop until the writer goes dead (peer disconnect) or
+	// returns voluntarily.
+	void DispatchEvents(const CHttpServer::Request &req,
+	                    CHttpServer::Writer &writer,
+	                    unsigned &http_status,
+	                    std::string &content_type,
+	                    std::map<std::string, std::string> &response_headers);
+
+	// Synchronous preflight for the SSE path. Runs on the I/O thread
+	// BEFORE the worker thread is spawned and BEFORE the 32-slot
+	// streaming-session budget is touched. Returns boost::none to
+	// admit the connection; returns a 401/403/429 Response to short-
+	// circuit unauth peers without burning a slot.
+	boost::optional<CHttpServer::Response> PreflightEvents(
+		const CHttpServer::Request &req);
+
+private:
+	// Inner routing — picks the right Handle*() based on path/method,
+	// returns a fully-formed response. The public Dispatch wraps this
+	// with the ETag stamp + If-None-Match → 304 conversion
+	// (GET/HEAD on a 200 only).
+	CHttpServer::Response DispatchToHandler(const CHttpServer::Request &req);
+public:
+
+	// Test-visible accessors; the auth-state containers are exposed
+	// so AuthTest can drive the rate-limit and revocation paths
+	// without standing up a full HTTP server.
+	webapi::CRevocationSet &Revocations()  { return m_revocations; }
+	webapi::CRateLimiter   &RateLimiter() { return m_rateLimiter; }
+
+private:
+	CHttpServer::Response HandleVersion (const CHttpServer::Request &);
+	CHttpServer::Response HandleLogin   (const CHttpServer::Request &);
+	CHttpServer::Response HandleLogout  (const CHttpServer::Request &);
+	CHttpServer::Response HandleSession (const CHttpServer::Request &);
+	CHttpServer::Response HandleStatus  (const CHttpServer::Request &);
+	CHttpServer::Response HandleDownloads      (const CHttpServer::Request &);
+	// `key` accepts the lowercase 32-char hex hash OR the decimal ECID.
+	CHttpServer::Response HandleDownloadDetail (const CHttpServer::Request &,
+	                                            const std::string &key);
+	// download lifecycle mutations.
+	CHttpServer::Response HandleDownloadAdd    (const CHttpServer::Request &);
+	CHttpServer::Response HandleDownloadPatch  (const CHttpServer::Request &,
+	                                            const std::string &key);
+	// clear completed downloads.
+	CHttpServer::Response HandleDownloadDelete (const CHttpServer::Request &,
+	                                            const std::string &key);
+	CHttpServer::Response HandleDownloadsClearCompleted(const CHttpServer::Request &);
+	// server lifecycle.
+	CHttpServer::Response HandleServerAdd      (const CHttpServer::Request &);
+	CHttpServer::Response HandleServerConnect  (const CHttpServer::Request &,
+	                                            const std::string &ecid_str);
+	CHttpServer::Response HandleServerDelete   (const CHttpServer::Request &,
+	                                            const std::string &ecid_str);
+	// Refresh the server list from a `server.met` URL — operator-
+	// curated server-list update, same EC op the desktop GUI's "Update
+	// from URL" button uses.
+	CHttpServer::Response HandleServerUpdateFromUrl(const CHttpServer::Request &);
+	// Address-keyed aliases that resolve {ip}:{port} to the ECID and
+	// delegate to HandleServerConnect / HandleServerDelete. Lets
+	// clients work without first having to GET /servers to learn the
+	// ECID for a known address.
+	CHttpServer::Response HandleServerConnectByAddress(
+		const CHttpServer::Request &, const std::string &ip_port);
+	CHttpServer::Response HandleServerDeleteByAddress(
+		const CHttpServer::Request &, const std::string &ip_port);
+	// preferences PATCH.
+	CHttpServer::Response HandlePreferencesPatch(const CHttpServer::Request &);
+	// connection control.
+	CHttpServer::Response HandleNetworksConnect (const CHttpServer::Request &);
+	CHttpServer::Response HandleNetworksDisconnect(const CHttpServer::Request &);
+	CHttpServer::Response HandleKadBootstrap    (const CHttpServer::Request &);
+	// shared file priority PATCH. `key` = hash OR ECID.
+	CHttpServer::Response HandleSharedPatch     (const CHttpServer::Request &,
+	                                             const std::string &key);
+
+	// Static-frontend fallthrough. Resolves `url_path` under
+	// ServerCfg().static_root, returns the file with a content-type
+	// derived from its extension. Returns 404 when static serving is
+	// disabled (StaticRoot empty), when the file is absent, or when
+	// the resolved path escapes static_root (realpath containment).
+	// Falls back to index.html for extension-less paths so SPA deep
+	// links work. Supports If-None-Match → 304 via mtime+size ETag.
+	// Never requires auth — the shell is public; the API calls it
+	// makes still hit the per-handler role gates.
+	CHttpServer::Response ServeStaticFile      (const CHttpServer::Request &,
+	                                             const std::string &url_path);
+	// Rescan shared directories — amuled re-walks the configured share
+	// roots and re-publishes whatever's there. Parameterless EC op
+	// (EC_OP_SHAREDFILES_RELOAD).
+	CHttpServer::Response HandleSharedReload    (const CHttpServer::Request &);
+	// categories CRUD.
+	CHttpServer::Response HandleCategoryCreate  (const CHttpServer::Request &);
+	CHttpServer::Response HandleCategoryUpdate  (const CHttpServer::Request &,
+	                                             const std::string &index_str);
+	CHttpServer::Response HandleCategoryDelete  (const CHttpServer::Request &,
+	                                             const std::string &index_str);
+	// search.
+	CHttpServer::Response HandleSearchStart    (const CHttpServer::Request &);
+	CHttpServer::Response HandleSearchStop     (const CHttpServer::Request &);
+	CHttpServer::Response HandleSearchDownload (const CHttpServer::Request &,
+	                                            const std::string &hash);
+	CHttpServer::Response HandleClients        (const CHttpServer::Request &);
+	CHttpServer::Response HandleSharedList     (const CHttpServer::Request &);
+	CHttpServer::Response HandleServers        (const CHttpServer::Request &);
+	CHttpServer::Response HandleKad            (const CHttpServer::Request &);
+	CHttpServer::Response HandleCategories     (const CHttpServer::Request &);
+	CHttpServer::Response HandlePreferences    (const CHttpServer::Request &);
+	CHttpServer::Response HandleLogAmule       (const CHttpServer::Request &);
+	CHttpServer::Response HandleLogServerinfo  (const CHttpServer::Request &);
+	// Log reset mutations. Both clear the corresponding buffer on
+	// amuled's side via the EC_OP_RESET_LOG / EC_OP_CLEAR_SERVERINFO
+	// opcodes and invalidate / clear amuleapi's local mirror so the
+	// next GET reflects the post-reset state immediately (the
+	// refresher's incremental append-only path can't shrink the
+	// amule-log cache, and the server-info lazy cache would otherwise
+	// keep serving stale text until its TTL elapses).
+	CHttpServer::Response HandleLogAmuleReset      (const CHttpServer::Request &);
+	CHttpServer::Response HandleLogServerinfoReset (const CHttpServer::Request &);
+	CHttpServer::Response HandleStatsTree      (const CHttpServer::Request &);
+	CHttpServer::Response HandleStatsGraph     (const CHttpServer::Request &,
+	                                            const std::string &graph);
+	CHttpServer::Response HandleSearchResults  (const CHttpServer::Request &);
+
+	const CAmuleApiConfig    &m_config;
+	CJwt                     &m_jwt;
+	webapi::CState           &m_state;
+	CamuleapiApp             &m_app;
+	webapi::CRevocationSet    m_revocations;
+
+	// Cached resolution of the static-frontend root. Conf-side
+	// `[Server]/StaticRoot` wins; an empty conf value falls back to
+	// the install-path discovery chain (ResolveDefaultStaticDir).
+	// Resolved on first ServeStaticFile call, then memoized for the
+	// daemon's lifetime — operators editing the conf at runtime are
+	// expected to restart amuleapi.
+	mutable std::string       m_static_root_cache;
+	mutable bool              m_static_root_resolved = false;
+
+	// ETag memoization keyed on (request target, snapshot version).
+	// Every 200 GET/HEAD runs MD5 over the whole body for ETag — on a
+	// 10K-shared-file daemon /downloads is multi-MB and this is the
+	// dominant CPU cost of the safe-method path. Cache against
+	// `CState::SnapshotAt()` so two GETs for the same target between
+	// ticks return identical bodies + ETags. On overflow the cache
+	// is cleared wholesale (typical working set is well below cap;
+	// the bound is just a memory backstop).
+	mutable std::mutex
+		m_etagCacheMu;
+	struct EtagCacheEntry {
+		std::time_t snapshot_at = 0;
+		std::string etag;
+	};
+	std::map<std::string, EtagCacheEntry>
+		m_etagCache;
+	static constexpr std::size_t kEtagCacheCapacity = 512;
+	// Login-specific failure counter. Tight thresholds (driven by
+	// the operator's `[Auth]/Login*` config) — humans typing
+	// passwords rarely fail >5 times in 60 s, so a tight cap is
+	// the right shape for password-guessing defence.
+	webapi::CRateLimiter      m_rateLimiter;
+	// Generic 401 failure counter — covers logout, session, events,
+	// and every mutation endpoint. Looser thresholds than login
+	// because a misconfigured CI runner or a tab whose cookie just
+	// expired shouldn't lock the user out for five minutes after
+	// a handful of requests, but a credential-stuffing attempt that
+	// burns through stolen bearer tokens DOES need a brake. Default
+	// 30 failures in 60 s → 5 min lockout (set in the dispatcher
+	// ctor below).
+	webapi::CRateLimiter      m_authRateLimiter;
+
+	// Lazy-fetch TTL caches. Each cache stores the
+	// snapshot value PLUS the wall-clock time at fetch so handlers
+	// can render `snapshot_at` against the actual freshness, not the
+	// refresher's tick boundary. TTL coalesces concurrent burst reads
+	// (1 s default; per design call). Fetcher lambdas
+	// acquire `m_app.m_ec_mtx` AFTER the cache's own mutex — single
+	// flight: a second concurrent miss waits on the cache mutex and
+	// reads the just-stored value.
+	using TtlPair_StatsTree  = std::pair<webapi::StatsTreeNode,                     std::time_t>;
+	using TtlPair_StatsGraphs= std::pair<webapi::StatsGraphs,                       std::time_t>;
+	using TtlPair_ServerInfo = std::pair<webapi::ServerInfoLog,                     std::time_t>;
+	webapi::CTtlCache<TtlPair_StatsTree>    m_stats_tree_cache;
+	webapi::CTtlCache<TtlPair_StatsGraphs>  m_stats_graphs_cache;
+	webapi::CTtlCache<TtlPair_ServerInfo>   m_server_info_cache;
+	// /search/results is no longer cached here — the refresher owns
+	// the polling while a search is active (see CState::SearchProgress
+	// + RefresherTick). POST /search calls m_state.MarkSearchStarted.
+};
+
+
+#endif // WEBAPI_API_H
diff --git a/src/webapi/App.cpp b/src/webapi/App.cpp
new file mode 100644
index 0000000000..2d57d6ae75
--- /dev/null
+++ b/src/webapi/App.cpp
@@ -0,0 +1,573 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#include "App.h"
+
+#include "Api.h"
+#include "HttpServer.h"
+#include "Jwt.h"
+#include "Refresher.h"
+
+#include "MD4Hash.h"
+#include "config.h"     // VERSION
+
+#include <common/Format.h>
+#include <common/MD5Sum.h>
+
+#include <wx/cmdline.h>
+
+#include <atomic>
+#include <chrono>
+#include <csignal>
+#include <cstring>
+#include <cstdlib>
+#include <iostream>
+#include <thread>
+
+
+IMPLEMENT_APP(CamuleapiApp)
+
+
+namespace {
+
+// Signal-safe shutdown gate. SIGINT/SIGTERM flip the flag; the wxApp
+// main loop polls it every 250 ms. A signalfd-driven path would be
+// cleaner, but the polling cost is one atomic-load per tick and the
+// code path stays portable to launchd/Windows (which don't have
+// signalfd).
+std::atomic<bool> g_shutdownRequested{false};
+
+void RequestShutdown(int)
+{
+	g_shutdownRequested.store(true, std::memory_order_release);
+}
+
+}  // namespace
+
+
+CamuleapiApp::CamuleapiApp()  = default;
+CamuleapiApp::~CamuleapiApp() = default;
+
+
+void CamuleapiApp::OnInitCmdLine(wxCmdLineParser &parser)
+{
+	// Pulls in --host / --port / --password / --config-dir / --quiet /
+	// --verbose / --locale. The base appname becomes the executable
+	// name in usage text.
+	CaMuleExternalConnector::OnInitCmdLine(parser, "amuleapi");
+
+	parser.AddOption("", "bind",
+		_("HTTP server bind address. (default: 127.0.0.1, override of amuleapi.conf [Server]/BindAddress)"),
+		wxCMD_LINE_VAL_STRING, wxCMD_LINE_PARAM_OPTIONAL);
+	parser.AddOption("", "http-port",
+		_("HTTP server port. (default: 4713, override of amuleapi.conf [Server]/Port)"),
+		wxCMD_LINE_VAL_NUMBER, wxCMD_LINE_PARAM_OPTIONAL);
+	parser.AddOption("", "config-dir",
+		_("Path to amuleapi config dir (default: per-platform aMule data dir)."),
+		wxCMD_LINE_VAL_STRING, wxCMD_LINE_PARAM_OPTIONAL);
+	parser.AddOption("", "set-admin-pass",
+		_("Hash <plain> with MD5 and write it as the admin password into amuleapi-passwords (mode 0600), then exit."),
+		wxCMD_LINE_VAL_STRING, wxCMD_LINE_PARAM_OPTIONAL);
+	parser.AddOption("", "set-guest-pass",
+		_("Hash <plain> with MD5 and write it as the guest password into amuleapi-passwords (mode 0600), then exit."),
+		wxCMD_LINE_VAL_STRING, wxCMD_LINE_PARAM_OPTIONAL);
+	parser.AddSwitch("", "foreground",
+		_("Stay in the foreground; default."),
+		wxCMD_LINE_PARAM_OPTIONAL);
+	// --daemon was reserved but never read — landed as a no-op switch.
+	// Dropped to avoid implying detach support that isn't here yet.
+	// Operators wanting fork-into-background today wrap amuleapi in
+	// systemd/launchd/`nohup` like any other long-running CLI.
+}
+
+
+bool CamuleapiApp::OnCmdLineParsed(wxCmdLineParser &parser)
+{
+	// Capture the amuleapi-specific options BEFORE delegating to the
+	// base, because the base call may exit early on --help.
+	if (parser.Found("bind", &m_cliBindAddress)) {
+		m_cliHasBindAddress = true;
+	}
+	if (parser.Found("http-port", &m_cliHttpPort)) {
+		m_cliHasHttpPort = true;
+	}
+	parser.Found("config-dir", &m_cliConfigDirOverride);
+	if (parser.Found("set-admin-pass", &m_cliSetAdminPass)) {
+		m_cliHasSetAdminPass = true;
+	}
+	if (parser.Found("set-guest-pass", &m_cliSetGuestPass)) {
+		m_cliHasSetGuestPass = true;
+	}
+	// The base class reads --host / --port / --password into m_host /
+	// m_port / m_password before we get here, but it offers no "did
+	// the user actually pass this?" predicate of its own — m_host
+	// defaults to "127.0.0.1" unconditionally and m_port to 4712. We
+	// poll the parser directly here so LoadAmuleapiConfig() can tell
+	// "operator explicitly passed --host=127.0.0.1" apart from
+	// "operator passed nothing and the base class filled in the
+	// default", and only apply the amuleapi.conf override in the
+	// second case. Same shape as the bind / http-port branches above.
+	m_cliHasEcHost     = parser.Found("host");
+	m_cliHasEcPort     = parser.Found("port");
+	m_cliHasEcPassword = parser.Found("password");
+
+	return CaMuleExternalConnector::OnCmdLineParsed(parser);
+}
+
+
+bool CamuleapiApp::OnInit()
+{
+	if (!CaMuleExternalConnector::OnInit()) {
+		return false;
+	}
+
+	// Resolve the config dir. Order: explicit --config-dir > whatever
+	// the base class picked (m_configDir, populated from --config-file
+	// or the platform default) > wxStandardPaths::GetUserDataDir().
+	wxString config_dir = m_cliConfigDirOverride.IsEmpty()
+		? m_configDir
+		: m_cliConfigDirOverride;
+	if (config_dir.IsEmpty()) {
+		config_dir = DefaultConfigDir();
+	}
+
+	if (!LoadAmuleapiConfig()) {
+		// Error already printed via Show(...).
+		return false;
+	}
+
+	// Construct the SSE bus once the operator-tunable capacity is
+	// known. Below the floor is clamped by CEventBus itself.
+	m_event_bus = std::unique_ptr<webapi::CEventBus>(
+		new webapi::CEventBus(
+			m_apiConfig.StreamingCfg().event_bus_ring_capacity));
+
+	// CLI override hooks. set-*-pass exits immediately after writing.
+	if (m_cliHasSetAdminPass || m_cliHasSetGuestPass) {
+		// Both options run as one-shot CLI flows. Operators script
+		// these like `amuleapi --set-admin-pass=... && systemctl
+		// restart amuleapi` — they MUST see the non-zero exit code on
+		// disk-full / mode-bit rejection / etc., otherwise the
+		// chain runs against the half-written file. Returning false
+		// from OnInit() would cancel wxApp::OnRun() but still exit 0,
+		// so we std::exit() here with the real return code.
+		const int rc = m_cliHasSetAdminPass
+			? RunSetAdminPass()
+			: RunSetGuestPass();
+		std::exit(rc);
+	}
+
+	return true;
+}
+
+
+bool CamuleapiApp::LoadAmuleapiConfig()
+{
+	wxString config_dir = m_cliConfigDirOverride.IsEmpty()
+		? m_configDir
+		: m_cliConfigDirOverride;
+	if (config_dir.IsEmpty()) {
+		config_dir = DefaultConfigDir();
+		// Persist the resolved dir back into m_configDir so the base
+		// class's later --write-config (and any subclasses) see the
+		// same path.
+		m_configDir = config_dir;
+	}
+
+	if (!m_apiConfig.Load(config_dir)) {
+		Show(CFormat("amuleapi: failed to load config: %s\n")
+			% wxString::FromUTF8(m_apiConfig.LastError().c_str()));
+		return false;
+	}
+
+	// Wire the EC connection params into the base-class fields that
+	// ConnectAndRun reads. CLI --host/--port/--password (captured via
+	// wxCmdLineParser::Found() in OnCmdLineParsed) win over
+	// amuleapi.conf. The old "is the field still at the default
+	// value?" heuristic conflated "operator didn't pass" with
+	// "operator explicitly passed the default" — so a literal
+	// `amuleapi --host=127.0.0.1` would be silently overwritten by
+	// the config file. The has-flag predicates are unambiguous.
+	if (!m_cliHasEcHost) {
+		const auto &h = m_apiConfig.EcCfg().host;
+		if (!h.empty()) m_host = wxString::FromUTF8(h.c_str());
+	}
+	if (!m_cliHasEcPort) {
+		m_port = static_cast<long>(m_apiConfig.EcCfg().port);
+	}
+	if (!m_cliHasEcPassword && !m_apiConfig.EcCfg().password.empty()) {
+		// amuleapi.conf [EC]/Password is plaintext; the base class
+		// expects an MD5-hashed CMD4Hash (because that's what amuled
+		// stores). MD5-hash here so a one-line amuleapi.conf edit
+		// gives the operator a working setup.
+		const wxString plain = wxString::FromUTF8(
+			m_apiConfig.EcCfg().password.c_str());
+		m_password.Decode(MD5Sum(plain).GetHash());
+	}
+
+	return true;
+}
+
+
+int CamuleapiApp::RunSetAdminPass()
+{
+	const wxString hashed = MD5Sum(m_cliSetAdminPass).GetHash();
+	if (!m_apiConfig.WritePasswordsFile(
+			m_apiConfig.ConfigDir(),
+			std::string(hashed.utf8_str()),
+			m_apiConfig.GuestPasswordMd5())) {
+		Show(CFormat("amuleapi: --set-admin-pass failed: %s\n")
+			% wxString::FromUTF8(m_apiConfig.LastError().c_str()));
+		return 1;
+	}
+	Show(_("amuleapi: admin password updated.\n"));
+	return 0;
+}
+
+
+int CamuleapiApp::RunSetGuestPass()
+{
+	const wxString hashed = MD5Sum(m_cliSetGuestPass).GetHash();
+	if (!m_apiConfig.WritePasswordsFile(
+			m_apiConfig.ConfigDir(),
+			m_apiConfig.AdminPasswordMd5(),
+			std::string(hashed.utf8_str()))) {
+		Show(CFormat("amuleapi: --set-guest-pass failed: %s\n")
+			% wxString::FromUTF8(m_apiConfig.LastError().c_str()));
+		return 1;
+	}
+	Show(_("amuleapi: guest password updated.\n"));
+	return 0;
+}
+
+
+int CamuleapiApp::OnRun()
+{
+	// Install signal handlers before the HTTP server starts so a
+	// signal during bring-up doesn't default-terminate the daemon.
+	//
+	// sigaction (not std::signal) — std::signal's "reset to SIG_DFL
+	// after firing" is implementation-defined (musl/Alpine, older
+	// BSDs trip it), so a second SIGINT would terminate mid-shutdown.
+	// SA_RESTART so blocking syscalls on the EC socket don't return
+	// EINTR. Windows lacks sigaction; fall back to std::signal there.
+#ifndef _WIN32
+	struct sigaction sa;
+	std::memset(&sa, 0, sizeof(sa));
+	sa.sa_handler = RequestShutdown;
+	sigemptyset(&sa.sa_mask);
+	sigaddset(&sa.sa_mask, SIGINT);
+	sigaddset(&sa.sa_mask, SIGTERM);
+#ifdef SIGHUP
+	sigaddset(&sa.sa_mask, SIGHUP);
+#endif
+	sa.sa_flags = SA_RESTART;
+	::sigaction(SIGINT,  &sa, nullptr);
+	::sigaction(SIGTERM, &sa, nullptr);
+#ifdef SIGHUP
+	// SIGHUP is the "config reload" signal in long-running daemons.
+	// has no reload story (configs are read at startup only);
+	// treat SIGHUP as a soft shutdown so a systemd reload doesn't
+	// leave the daemon in a half-state.
+	::sigaction(SIGHUP,  &sa, nullptr);
+#endif
+#ifdef SIGPIPE
+	// SSE peers that disappear mid-write make Linux raise SIGPIPE on
+	// the next asio::write to the closed fd. We don't pass
+	// MSG_NOSIGNAL on any of the SSE socket writes (HttpServer.cpp),
+	// so without ignoring SIGPIPE here the default disposition kills
+	// the daemon on every dropped EventSource. Ignore it process-
+	// wide; the writes return EPIPE and the streaming-handler loop
+	// bails on the next writer.Alive() poll.
+	struct sigaction sa_ign;
+	std::memset(&sa_ign, 0, sizeof(sa_ign));
+	sa_ign.sa_handler = SIG_IGN;
+	sigemptyset(&sa_ign.sa_mask);
+	sa_ign.sa_flags = 0;
+	::sigaction(SIGPIPE, &sa_ign, nullptr);
+#endif
+#else  // _WIN32
+	std::signal(SIGINT,  RequestShutdown);
+	std::signal(SIGTERM, RequestShutdown);
+#endif
+
+	// ConnectAndRun does the EC bring-up (CRemoteConnect, ConnectToCore)
+	// and then calls TextShell — which we've overridden so the daemon's
+	// main loop runs there. On EC failure ConnectAndRun returns without
+	// ever entering TextShell, which is the correct outcome for a
+	// daemon that has nothing to do without amuled.
+	ConnectAndRun(wxT("amuleapi"), wxString::FromAscii(VERSION));
+	return 0;
+}
+
+
+void CamuleapiApp::TextShell(const wxString &/*prompt*/)
+{
+	// Resolve bind addr + port. CLI takes precedence over amuleapi.conf.
+	std::string bind = m_apiConfig.ServerCfg().bind_address;
+	unsigned    port = m_apiConfig.ServerCfg().port;
+	if (m_cliHasBindAddress && !m_cliBindAddress.IsEmpty()) {
+		bind = std::string(m_cliBindAddress.utf8_str());
+	}
+	if (m_cliHasHttpPort && m_cliHttpPort > 0 && m_cliHttpPort < 65536) {
+		port = static_cast<unsigned>(m_cliHttpPort);
+	}
+
+	// Bind-time hard gate against the "listening publicly with no
+	// password configured" footgun. A daemon bound to a routable
+	// interface before the operator runs `amuleapi --set-admin-pass`
+	// would still answer the unauth surface (/api/v0/version) — and
+	// any future read-without-auth surface — even though logins
+	// return 503. Refuse to start instead.
+	//
+	// Loopback bind + empty passwords is fine; first-run flow IS
+	// "start on loopback, then run --set-admin-pass".
+	const bool non_loopback = (bind != "127.0.0.1"
+	                       && bind != "::1"
+	                       && bind != "localhost");
+	const bool no_pass = m_apiConfig.AdminPasswordMd5().empty()
+	                  && m_apiConfig.GuestPasswordMd5().empty();
+	if (non_loopback && no_pass) {
+		Show(CFormat(
+			_("amuleapi: refusing to start with BindAddress=%s and no "
+			  "admin/guest password configured — this would expose the "
+			  "REST surface to anyone reachable on that interface. "
+			  "Either bind to 127.0.0.1, or run "
+			  "`amuleapi --set-admin-pass=<plain>` first.\n"))
+			% wxString::FromUTF8(bind.c_str()));
+		return;
+	}
+
+	// Build the JWT machinery from the loaded secret + a dispatcher
+	// that holds the rate-limiter + revocation set by value. The
+	// dispatcher reaches the State cache through CamuleapiApp; the
+	// lambda below pins the dispatcher's lifetime to App's.
+	m_jwt        = std::unique_ptr<CJwt>(new CJwt(m_apiConfig.JwtSecret()));
+	m_dispatcher = std::unique_ptr<CApiDispatcher>(
+		new CApiDispatcher(m_apiConfig, *m_jwt, m_state, *this));
+	CApiDispatcher *const dispatcher = m_dispatcher.get();
+	auto handler = [dispatcher](const CHttpServer::Request &req) {
+		return dispatcher->Dispatch(req);
+	};
+
+	// streaming resolver + handler for /api/v0/events. The
+	// resolver picks every GET that matches the path (auth is
+	// enforced inside the streaming handler — same role gate as
+	// regular handlers).
+	auto streaming_resolver = [](const CHttpServer::Request &req) {
+		if (req.method != "GET" && req.method != "HEAD") return false;
+		// Tolerate optional ?query / trailing slashes.
+		const std::string &t = req.target;
+		const std::size_t q = t.find('?');
+		std::string path = (q == std::string::npos) ? t : t.substr(0, q);
+		return path == "/api/v0/events";
+	};
+	auto streaming_handler = [dispatcher](
+			const CHttpServer::Request &req,
+			CHttpServer::Writer &writer,
+			unsigned &http_status, std::string &content_type,
+			std::map<std::string, std::string> &response_headers) {
+		dispatcher->DispatchEvents(req, writer, http_status,
+		                           content_type, response_headers);
+	};
+	// Preflight runs synchronously before the SSE worker thread is
+	// spawned: short-circuit unauth requests with the standard 401
+	// body so they can't tie up a streaming slot for the read-
+	// timeout window.
+	auto streaming_preflight = [dispatcher](
+			const CHttpServer::Request &req)
+		-> boost::optional<CHttpServer::Response> {
+		return dispatcher->PreflightEvents(req);
+	};
+
+	m_http = std::unique_ptr<CHttpServer>(new CHttpServer());
+	if (!m_http->Start(bind, port, handler,
+	                   streaming_resolver, streaming_handler,
+	                   streaming_preflight)) {
+		Show(CFormat("amuleapi: HTTP server failed to start: %s\n")
+			% wxString::FromUTF8(m_http->LastError().c_str()));
+		return;
+	}
+
+	Show(CFormat(_("amuleapi: listening on http://%s:%d/\n"))
+		% wxString::FromUTF8(bind.c_str())
+		% static_cast<int>(port));
+	Show(CFormat(_("amuleapi: config dir %s\n"))
+		% m_apiConfig.ConfigDir());
+	Show(CFormat(_("amuleapi: aMule version %s; api v0\n"))
+		% wxString::FromAscii(VERSION));
+
+	// Refresher loop. One tick per second; HTTP threads read State
+	// concurrently. EC roundtrips run on this thread (CRemoteConnect's
+	// owner) but go through `SendRecvSerialized` so HTTP-thread
+	// mutations can also call it under m_ec_mtx.
+	//
+	// `was_failed` tracks the success/failure edge so we wipe list
+	// caches on the rising edge (failed → succeeded). The server's
+	// CValueMap was reset across the disconnect; clearing first stops
+	// stale entries lingering forever in the INC-delta path.
+	bool was_failed = false;
+	// Target 1 s wall-clock between tick starts. Measure the tick,
+	// sleep the remainder; warn if a tick overruns the 3 s budget
+	// (typically signals an EC stall or runaway SendRecvSerialized).
+	// Fixed `tick + 4 × 250 ms sleep` drifts under EC-mutex contention.
+	constexpr auto kTargetCycle  = std::chrono::seconds(1);
+	constexpr auto kSliceMs      = std::chrono::milliseconds(250);
+	constexpr auto kOverrunWarn  = std::chrono::seconds(3);
+	// Fail-loud on a sustained EC blackout. RefresherTick returns
+	// false on any null packet from SendRecvSerialized — typically
+	// amuled crashed, was killed, or the EC socket dropped. Today
+	// the loop just retries forever; the daemon stays up serving
+	// 503 ec_unavailable from every endpoint. After ~30 s of
+	// failed ticks, log a sharp WARN so the operator's journal
+	// shows it; after ~5 min, exit cleanly so a process supervisor
+	// (systemd, launchd, docker restart=always) can bring the
+	// whole pair back up. Reset on the first success.
+	constexpr unsigned kEcFailWarnAfter   = 30;
+	constexpr unsigned kEcFailExitAfter   = 300;
+	unsigned ec_consecutive_failures = 0;
+	bool     ec_warn_logged          = false;
+	while (!g_shutdownRequested.load(std::memory_order_acquire)) {
+		const auto cycle_start = std::chrono::steady_clock::now();
+		if (was_failed) {
+			m_state.ResetLists();
+		}
+		const bool ok = webapi::RefresherTick(*this, m_state);
+		if (ok) {
+			m_state.MarkTickSuccess();
+			was_failed = false;
+			ec_consecutive_failures = 0;
+			ec_warn_logged          = false;
+			// Sole writer of m_last_seen. SSE-event publication runs
+			// here, NOT inside RefresherTick — so mutation handlers
+			// calling RefresherTick inline from the HTTP thread
+			// don't race with this loop's diff walk.
+			webapi::EmitDiffsForEventBus(*this, m_state);
+		} else {
+			m_state.MarkTickFailure();
+			was_failed = true;
+			++ec_consecutive_failures;
+			if (!ec_warn_logged
+			    && ec_consecutive_failures >= kEcFailWarnAfter) {
+				std::cerr << "amuleapi: WARN EC has returned null "
+				             "for "
+				          << ec_consecutive_failures
+				          << " consecutive ticks (~"
+				          << ec_consecutive_failures
+				          << " s). amuled may be down or the EC "
+				             "socket may have dropped. Will exit "
+				             "after "
+				          << kEcFailExitAfter
+				          << " failed ticks so a process supervisor "
+				             "can restart the pair.\n";
+				ec_warn_logged = true;
+			}
+			if (ec_consecutive_failures >= kEcFailExitAfter) {
+				std::cerr << "amuleapi: FATAL EC has been silent "
+				             "for "
+				          << ec_consecutive_failures
+				          << " consecutive ticks. Exiting.\n";
+				g_shutdownRequested.store(true,
+					std::memory_order_release);
+			}
+		}
+		const auto tick_end       = std::chrono::steady_clock::now();
+		const auto tick_duration  = tick_end - cycle_start;
+		if (tick_duration >= kOverrunWarn) {
+			const auto ms = std::chrono::duration_cast<
+				std::chrono::milliseconds>(tick_duration).count();
+			std::cerr << "amuleapi: WARN refresher tick took "
+			          << ms << " ms (> "
+			          << std::chrono::duration_cast<
+			              std::chrono::milliseconds>(kOverrunWarn).count()
+			          << " ms budget) — likely EC-mutex contention or a "
+			             "stalled SendRecvSerialized.\n";
+		}
+		// Sleep the REMAINDER of the target cycle in small slices so
+		// shutdown latency stays bounded. A tick that already
+		// consumed >= the budget skips the sleep entirely so the
+		// next cycle starts immediately.
+		auto deadline = cycle_start + kTargetCycle;
+		while (true) {
+			if (g_shutdownRequested.load(std::memory_order_acquire)) break;
+			const auto now = std::chrono::steady_clock::now();
+			if (now >= deadline) break;
+			const auto remaining = deadline - now;
+			std::this_thread::sleep_for(
+				remaining < kSliceMs ? remaining : kSliceMs);
+		}
+	}
+
+	Show(_("amuleapi: shutdown signal received; stopping...\n"));
+}
+
+
+const CECPacket *CamuleapiApp::SendRecvSerialized(const CECPacket *request)
+{
+	std::lock_guard<std::mutex> lock(m_ec_mtx);
+	return SendRecvMsg_v2(request);
+}
+
+
+bool CamuleapiApp::IsServerPartialUpdateActive()
+{
+	// Inherited from CaMuleExternalConnector. No mutex needed —
+	// it's a const bool snapshot taken at login.
+	return CaMuleExternalConnector::IsServerPartialUpdateActive();
+}
+
+
+int CamuleapiApp::OnExit()
+{
+	// Tear down in reverse construction order: HTTP server first
+	// (no in-flight Dispatch can reach a dangling dispatcher), then
+	// dispatcher (references m_jwt), then m_jwt.
+	//
+	// Wake SSE drainers BEFORE Stop() returns so workers blocked on
+	// the 15 s heartbeat bail out and release their dispatcher refs.
+	// Without this, `m_dispatcher.reset()` below would race a
+	// drainer mid-write against a destroyed dispatcher → UAF in the
+	// signal-driven shutdown. m_http->Stop()'s join is then bounded.
+	if (m_event_bus) m_event_bus->Shutdown();
+	if (m_http) {
+		m_http->Stop();
+		m_http.reset();
+	}
+	m_dispatcher.reset();
+	m_jwt.reset();
+	return CaMuleExternalConnector::OnExit();
+}
+
+
+// Stub functions needed by the linker because ExternalConnector.cpp
+// transitively references MuleNotify (via the EC tag handlers); the
+// daemon-side bodies live in the monolithic amule binary, and console
+// builds (amulecmd, amuleapi) supply no-ops since they never raise
+// GUI notifications.
+namespace MuleNotify
+{
+class CMuleNotiferBase;
+void HandleNotification(const CMuleNotiferBase&)       {}
+void HandleNotificationAlways(const CMuleNotiferBase&) {}
+}
diff --git a/src/webapi/App.h b/src/webapi/App.h
new file mode 100644
index 0000000000..17c731571d
--- /dev/null
+++ b/src/webapi/App.h
@@ -0,0 +1,182 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#ifndef WEBAPI_APP_H
+#define WEBAPI_APP_H
+
+#include <memory>
+
+#include "ExternalConnector.h"
+
+#include "AmuleApiConfig.h"
+#include "EventBus.h"
+#include "EventDiff.h"
+#include "State.h"
+
+#include "Jwt.h"
+#include "RLE.h"   // PartFileEncoderData
+
+#include <cstdint>
+#include <map>
+#include <mutex>
+
+
+class CApiDispatcher;
+class CECPacket;
+class CHttpServer;
+
+
+// amuleapi daemon entry. Inherits CaMuleExternalConnector to reuse
+// the EC bring-up machinery (CRemoteConnect, --host / --port /
+// --password, ZLIB negotiation, MD5 password handling). Adds the
+// amuleapi-specific CLI options (--bind, --http-port, --config-dir,
+// --set-{admin,guest}-pass), config-file loading via
+// CAmuleApiConfig, and a Boost.Beast HTTP server thread.
+//
+// TextShell is overridden so `ConnectAndRun` becomes "connect EC,
+// spawn the HTTP thread, run the refresher loop on this (wxApp)
+// thread, tear down on shutdown signal".
+//
+// Concurrent REST handlers reach EC only through
+// `SendRecvSerialized`, which holds a process-wide mutex around
+// every EC roundtrip — CRemoteConnect stays single-threaded as
+// required, and concurrent mutations + the refresher tick interleave
+// correctly.
+class CamuleapiApp : public CaMuleExternalConnector {
+public:
+	CamuleapiApp();
+	~CamuleapiApp();
+
+	const wxString GetGreetingTitle() override { return _("aMule REST API"); }
+
+	bool OnInit() override;
+	int  OnRun()  override;
+	int  OnExit() override;
+
+	// Serialized EC roundtrip. Takes the EC lock, calls
+	// SendRecvMsg_v2, releases. Callable from any thread; the
+	// refresher and mutation handlers funnel every EC call
+	// through here so amule's wx-socket-driven CRemoteConnect stays
+	// single-reader by construction.
+	//
+	// Returns the response packet on success or nullptr if EC has
+	// disconnected. Caller owns the returned packet.
+	const CECPacket *SendRecvSerialized(const CECPacket *request);
+
+	// True when amuled advertised EC_TAG_CAN_PARTIAL_UPDATE during
+	// login. Refresher uses this to decide between "trust the
+	// EC_TAG_FILE_REMOVED markers" and the legacy "bulk-delete
+	// entries we didn't see this tick" path.
+	bool IsServerPartialUpdateActive();
+
+	// Refresher needs the cache. Single CState instance per process.
+	webapi::CState &State() { return m_state; }
+
+	// Per-partfile RLE decoder state, persisted across ticks. amule's
+	// EC server sends GAP_STATUS / PART_STATUS as differentially-
+	// encoded blobs (each frame is XOR-deltaed against the previous
+	// decoded buffer) so the decoder MUST retain state across calls.
+	// Keyed by partfile ECID; entry erased when the file is removed.
+	//
+	// **Concurrency:** mutated only under `CState::m_mu` held
+	// EXCLUSIVE — typically inside a `MutateDownloads` writer lambda.
+	// `m_ec_mtx` is incidentally held across the same call stack
+	// (`SendRecvSerialized` takes it) but the State write lock is
+	// the actual serializer. The method name encodes the
+	// precondition so a code-review reader notices it.
+	std::map<std::uint32_t, PartFileEncoderData> &
+		PartfileRleStateRequireStateWriteLock() {
+		return m_partfile_rle;
+	}
+
+	// SSE event bus. The refresher publishes events after
+	// each successful tick; streaming-handler threads drain from
+	// here. Exposed by raw reference — CEventBus is internally
+	// thread-safe. Lazy-constructed in OnInit so the operator-
+	// configured ring capacity from amuleapi.conf is honored.
+	webapi::CEventBus &EventBus() { return *m_event_bus; }
+
+	// prior-tick snapshot used to compute event deltas.
+	// Owned by the App; mutated AFTER each successful refresher
+	// tick by `EmitDiffsAndUpdate`. Exposed so RefresherTick can
+	// reach it without re-routing through CState (which is read-
+	// only from the refresher's perspective post-tick).
+	webapi::LastSeenState &LastSeenForEvents() { return m_last_seen; }
+
+private:
+	void OnInitCmdLine(wxCmdLineParser &parser) override;
+	bool OnCmdLineParsed(wxCmdLineParser &parser) override;
+
+	// Loads amuleapi.conf + amuleapi-jwt-secret + amuleapi-passwords.
+	// Returns false on any unrecoverable error (missing required file,
+	// wrong mode bits on POSIX, malformed INI). The error has already
+	// been printed via Show() at the point of return.
+	bool LoadAmuleapiConfig();
+
+	// CLI-only flows. Both write the requested file under
+	// m_amuleapiConfigDir with mode 0600 and exit immediately —
+	// they never start the HTTP server or connect to EC.
+	int RunSetAdminPass();
+	int RunSetGuestPass();
+
+	// TextShell override drives the refresher loop and the HTTP
+	// server. Called by CaMuleExternalConnector::ConnectAndRun after
+	// the EC connection is established; we override it so the daemon
+	// never enters the interactive readline path that amulecmd uses.
+	void TextShell(const wxString &prompt) override;
+
+	CAmuleApiConfig                 m_apiConfig;
+	webapi::CState                  m_state;
+	std::mutex                      m_ec_mtx;   // serializes m_ECClient
+	std::unique_ptr<CJwt>           m_jwt;
+	std::unique_ptr<CApiDispatcher> m_dispatcher;
+	std::unique_ptr<CHttpServer>    m_http;
+	std::map<std::uint32_t, PartFileEncoderData> m_partfile_rle;
+	std::unique_ptr<webapi::CEventBus>           m_event_bus;
+	webapi::LastSeenState                        m_last_seen;
+
+	// CLI capture: --bind / --http-port override the matching keys in
+	// amuleapi.conf when present. --set-*-pass and --foreground are
+	// runtime-mode toggles. The `m_cliHas*` flags discriminate between
+	// "operator passed nothing" and "operator passed the default
+	// value verbatim" — the base class' m_host / m_port / m_password
+	// fields have no such predicate of their own.
+	wxString m_cliBindAddress;
+	long     m_cliHttpPort       = 0;
+	wxString m_cliConfigDirOverride;
+	wxString m_cliSetAdminPass;
+	wxString m_cliSetGuestPass;
+	bool     m_cliHasBindAddress  = false;
+	bool     m_cliHasHttpPort     = false;
+	bool     m_cliHasSetAdminPass = false;
+	bool     m_cliHasSetGuestPass = false;
+	// Did the operator pass --host / --port / --password explicitly?
+	bool     m_cliHasEcHost       = false;
+	bool     m_cliHasEcPort       = false;
+	bool     m_cliHasEcPassword   = false;
+};
+
+DECLARE_APP(CamuleapiApp)
+
+#endif // WEBAPI_APP_H
diff --git a/src/webapi/Auth.cpp b/src/webapi/Auth.cpp
new file mode 100644
index 0000000000..8000ab979d
--- /dev/null
+++ b/src/webapi/Auth.cpp
@@ -0,0 +1,237 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#include "Auth.h"
+
+#include "HeaderParse.h"
+
+#include <algorithm>
+#include <cctype>
+#include <cstdio>
+#include <cstring>
+
+// strncasecmp on POSIX is declared in <strings.h>. Glibc also exposes
+// it via <string.h>, but musl and the BSDs do not — be explicit so
+// the build doesn't depend on the implicit include. Mirror the shim
+// libwebcommon/HeaderParse.cpp already uses.
+#ifdef _WIN32
+#  define strncasecmp _strnicmp
+#else
+#  include <strings.h>
+#endif
+
+
+namespace webapi {
+
+
+// ---------- CRevocationSet ---------------------------------------
+
+void CRevocationSet::Revoke(const std::string &jti, std::time_t exp)
+{
+	std::lock_guard<std::mutex> lock(m_mu);
+	m_revoked[jti] = exp;
+	GcExpired();
+}
+
+
+bool CRevocationSet::IsRevoked(const std::string &jti) const
+{
+	std::lock_guard<std::mutex> lock(m_mu);
+	auto it = m_revoked.find(jti);
+	if (it == m_revoked.end()) return false;
+	// Lazy GC: if the entry has already expired, drop it. Saves a
+	// tick of memory and prevents stale entries from accumulating
+	// for tokens nobody will ever present again.
+	if (it->second <= std::time(nullptr)) {
+		m_revoked.erase(it);
+		return false;
+	}
+	return true;
+}
+
+
+std::size_t CRevocationSet::Size() const
+{
+	std::lock_guard<std::mutex> lock(m_mu);
+	return m_revoked.size();
+}
+
+
+void CRevocationSet::GcExpired() const
+{
+	// O(n) sweep over the revoked map, fired from every Revoke() and
+	// every Contains() check. Fine at amuleapi's expected scale (a
+	// single operator, a handful of admin/guest sessions per day);
+	// the map stays in the low hundreds even under aggressive
+	// re-login. If multi-tenant deployments ever raise the revoked
+	// population into the thousands, swap this for a min-heap keyed
+	// by `exp` so the GC pops a constant prefix per call instead of
+	// walking the whole structure.
+	const std::time_t now = std::time(nullptr);
+	for (auto it = m_revoked.begin(); it != m_revoked.end();) {
+		if (it->second <= now) {
+			it = m_revoked.erase(it);
+		} else {
+			++it;
+		}
+	}
+}
+
+
+// ---------- CRateLimiter -----------------------------------------
+
+CRateLimiter::Decision CRateLimiter::Check(const std::string &ip)
+{
+	std::lock_guard<std::mutex> lock(m_mu);
+	const std::time_t now = m_clock();
+	auto it = m_buckets.find(ip);
+	if (it == m_buckets.end()) return Decision{};
+
+	Bucket &b = it->second;
+	if (b.lockout_until > now) {
+		Decision d;
+		d.locked_out          = true;
+		d.retry_after_seconds = b.lockout_until - now;
+		return d;
+	}
+	// Lockout window expired — wipe the bucket so a stale lockout
+	// can't accidentally fire on the next Check after a long quiet
+	// period.
+	if (b.lockout_until != 0 && b.lockout_until <= now) {
+		b.lockout_until = 0;
+		b.failures.clear();
+	}
+	// Mirror NoteFailure's per-stamp expiry so Check is self-
+	// consistent. Otherwise stale stamps from a long-idle bucket
+	// remain in failures until the next NoteFailure fires, and a
+	// caller inspecting bucket size via a future debug surface would
+	// see counts that include already-out-of-window failures.
+	while (!b.failures.empty()
+	    && (now - b.failures.front()) > m_cfg.window_seconds) {
+		b.failures.pop_front();
+	}
+	return Decision{};
+}
+
+
+void CRateLimiter::NoteFailure(const std::string &ip)
+{
+	std::lock_guard<std::mutex> lock(m_mu);
+	const std::time_t now = m_clock();
+	Bucket &b = m_buckets[ip];
+
+	// Sliding window: drop any failure stamp older than
+	// `window_seconds`, then append now. Lockout fires when the live
+	// stamp count crosses `threshold`. Previously the bucket reset
+	// wholesale once `now - window_start > window_seconds`, which
+	// implemented a TUMBLING window — an attacker could split
+	// threshold-1 attempts across the two adjacent windows and
+	// never trip lockout. Per-stamp expiry closes the gap.
+	while (!b.failures.empty()
+	    && (now - b.failures.front()) > m_cfg.window_seconds) {
+		b.failures.pop_front();
+	}
+	b.failures.push_back(now);
+
+	if (b.failures.size() >= m_cfg.threshold) {
+		b.lockout_until = now + m_cfg.lockout_seconds;
+	}
+}
+
+
+void CRateLimiter::NoteSuccess(const std::string &ip)
+{
+	std::lock_guard<std::mutex> lock(m_mu);
+	m_buckets.erase(ip);
+}
+
+
+// ---------- Header extraction ------------------------------------
+
+std::string ExtractBearerToken(const std::string &authorization_header)
+{
+	// `Authorization: Bearer <jwt>` per RFC 6750 §2.1. Scheme name is
+	// case-insensitive; the token itself is the bare base64url
+	// triplet our own CJwt emits.
+	const char *prefix = "Bearer ";
+	const size_t plen  = std::strlen(prefix);
+	if (authorization_header.size() <= plen) return std::string();
+	if (strncasecmp(authorization_header.c_str(), prefix, plen) != 0) {
+		return std::string();
+	}
+	// Trim leading OWS after the scheme name (some clients add extra
+	// spaces; RFC 7230 §3.2.3 allows them).
+	size_t i = plen;
+	while (i < authorization_header.size()
+	       && (authorization_header[i] == ' ' || authorization_header[i] == '\t')) {
+		++i;
+	}
+	if (i >= authorization_header.size()) return std::string();
+	return authorization_header.substr(i);
+}
+
+
+std::string ExtractCookieValue(const std::string &cookie_header,
+                               const std::string &cookie_name)
+{
+	// Delegate to libwebcommon's pointer-arithmetic helper so the
+	// parsing rules (case-insensitive name match, `;` separators,
+	// OWS trimming) stay in one place.
+	const auto v = webcommon::FindCookieValue(
+		cookie_header.c_str(),
+		cookie_header.size(),
+		cookie_name.c_str());
+	if (!v.first || v.second == 0) return std::string();
+	return std::string(v.first, v.second);
+}
+
+
+// ---------- ISO-8601 ---------------------------------------------
+
+std::string FormatIso8601Utc(std::time_t t)
+{
+	std::tm out{};
+#ifdef _WIN32
+	gmtime_s(&out, &t);
+#else
+	gmtime_r(&t, &out);
+#endif
+	char buf[32];
+	const int n = std::snprintf(buf, sizeof(buf),
+		"%04d-%02d-%02dT%02d:%02d:%02dZ",
+		out.tm_year + 1900,
+		out.tm_mon  + 1,
+		out.tm_mday,
+		out.tm_hour,
+		out.tm_min,
+		out.tm_sec);
+	// snprintf's return is the bytes that *would* have been written.
+	// Our format produces exactly 20 chars + NUL, so anything else
+	// is a libc bug — return whatever we got rather than crashing.
+	if (n < 0) return std::string();
+	return std::string(buf, std::min<size_t>(n, sizeof(buf) - 1));
+}
+
+
+}  // namespace webapi
diff --git a/src/webapi/Auth.h b/src/webapi/Auth.h
new file mode 100644
index 0000000000..a8d299e4b8
--- /dev/null
+++ b/src/webapi/Auth.h
@@ -0,0 +1,177 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#ifndef WEBAPI_AUTH_H
+#define WEBAPI_AUTH_H
+
+#include <deque>
+
+#include <ctime>
+#include <functional>
+#include <map>
+#include <mutex>
+#include <set>
+#include <string>
+
+
+// State containers + helpers for the /auth/* surface. Live on the
+// amuleapi process side (not in libwebcommon) because they're stateful
+// and amuleweb has no use for them.
+//
+// Thread-safety model: today, every caller runs on the Boost.Asio I/O
+// thread (single io_context, single std::thread). The std::mutex in
+// each container is forward-compat insurance — the SSE channel adds
+// a heartbeat timer that fires on the same I/O thread, so the mutex
+// never contends in v0.1 — but a future worker-pool model gets
+// correctness for free.
+
+
+namespace webapi {
+
+
+// Server-side bearer-token revocation list. JWTs are stateless by
+// design; for /auth/logout to actually invalidate a token, the server
+// has to remember "this jti is dead until the JWT's exp".
+//
+// Memory cost: one entry per logged-out-but-still-unexpired token.
+// `jti` is 22 base64url chars (~24 bytes once the std::string SSO
+// boundary kicks in) + the exp timestamp + map overhead — call it
+// ~64 bytes per revoked token. Bounded by max-concurrent-users ×
+// 24 h (the JWT lifetime).
+//
+// GC: lazy on Revoke() — sweeps entries whose exp has already
+// passed. Cheap (~O(log n) lookup per sweep) and amortizes the work
+// across calls instead of needing a periodic timer.
+class CRevocationSet {
+public:
+	void Revoke(const std::string &jti, std::time_t exp);
+	bool IsRevoked(const std::string &jti) const;
+
+	// Test-visible inspection. Not exposed via the API — the
+	// revocation set is operator-internal.
+	std::size_t Size() const;
+
+private:
+	void GcExpired() const;
+
+	mutable std::mutex                              m_mu;
+	mutable std::map<std::string, std::time_t>      m_revoked;
+};
+
+
+// Per-IP sliding-window login rate limiter (). Tracks
+// failed `/auth/login` attempts, locks the offending IP out for
+// `lockout_seconds` once `threshold` failures land inside
+// `window_seconds`. A successful login resets the offender's bucket.
+//
+// Storage: std::unordered_map<ip_string, Bucket>. Real-world
+// amuleapi deployments serve a small population (LAN ops, single
+// operator), so the map stays under a few hundred entries even
+// under bot-scan load. No active GC; cold buckets get overwritten
+// when the offender comes back, and the daemon's process lifetime
+// bounds the worst case.
+class CRateLimiter {
+public:
+	struct Config {
+		unsigned    window_seconds   = 60;
+		unsigned    threshold        = 5;
+		unsigned    lockout_seconds  = 300;
+	};
+
+	// Clock injection. Default is std::time(nullptr); tests pass a
+	// controllable lambda so AuthTest can exercise the sliding-
+	// window logic in microseconds instead of spending five+
+	// real-time seconds sleeping between failures.
+	using Clock = std::function<std::time_t()>;
+
+	explicit CRateLimiter(Config cfg, Clock clock = nullptr)
+		: m_cfg(cfg),
+		  m_clock(clock ? std::move(clock)
+		                : [] { return std::time(nullptr); }) {}
+
+	struct Decision {
+		bool        locked_out          = false;
+		std::time_t retry_after_seconds = 0;
+	};
+
+	// Called BEFORE the password compare. If `locked_out` is true,
+	// the caller emits 429 with `Retry-After: <retry_after_seconds>`
+	// and never touches the credential path.
+	Decision Check(const std::string &ip);
+
+	// Called AFTER a failed credential compare. Updates the bucket
+	// and possibly arms the lockout for next time.
+	void NoteFailure(const std::string &ip);
+
+	// Called AFTER a successful credential compare. Drops the
+	// bucket so the user's next login isn't accounted against the
+	// previous failure streak.
+	void NoteSuccess(const std::string &ip);
+
+	const Config &Cfg() const { return m_cfg; }
+
+private:
+	struct Bucket {
+		// Sliding window of failure timestamps. The legacy `unsigned
+		// failure_count + std::time_t window_start` shape implemented
+		// a TUMBLING window (the count reset wholesale when the
+		// window expired) — an attacker could burn threshold-1
+		// failures in the last second of window N, threshold-1 more
+		// in the first second of window N+1, and never trip lockout.
+		// We now keep one timestamp per recorded failure (older than
+		// `window_seconds` evicted on each NoteFailure) so the
+		// trip happens whenever the live count crosses threshold,
+		// regardless of how the failures distribute across windows.
+		std::deque<std::time_t> failures;
+		std::time_t             lockout_until = 0;
+	};
+
+	Config                                          m_cfg;
+	Clock                                           m_clock;
+	mutable std::mutex                              m_mu;
+	std::map<std::string, Bucket>                   m_buckets;
+};
+
+
+// HTTP `Authorization: Bearer <jwt>` extractor. Returns the empty
+// string if the header is absent, doesn't start with `Bearer `, or
+// has no value past the space. Case-insensitive scheme compare
+// per RFC 6750 §2.1.
+std::string ExtractBearerToken(const std::string &authorization_header);
+
+
+// Extracts `<cookie_name>=<value>` from a Cookie header. Returns the
+// empty string on miss.
+std::string ExtractCookieValue(const std::string &cookie_header,
+                               const std::string &cookie_name);
+
+
+// ISO-8601 / RFC 3339 in UTC: "2026-06-19T11:00:00Z". 20-char fixed
+// length; clients can `Date.parse(...)` it.
+std::string FormatIso8601Utc(std::time_t t);
+
+
+}  // namespace webapi
+
+#endif // WEBAPI_AUTH_H
diff --git a/src/webapi/CMakeLists.txt b/src/webapi/CMakeLists.txt
new file mode 100644
index 0000000000..0333419b66
--- /dev/null
+++ b/src/webapi/CMakeLists.txt
@@ -0,0 +1,97 @@
+# amuleapi — REST API + SSE daemon. Standalone executable that
+# connects to amuled via the existing EC protocol (same wire as
+# amulecmd / amuleweb) and serves /api/v0/* over HTTP via Boost.Beast.
+
+add_executable (amuleapi
+	${CMAKE_SOURCE_DIR}/src/ExternalConnector.cpp
+	${CMAKE_SOURCE_DIR}/src/OtherFunctions.cpp
+	${CMAKE_SOURCE_DIR}/src/RLE.cpp
+	${CMAKE_SOURCE_DIR}/src/NetworkFunctions.cpp
+	${CMAKE_SOURCE_DIR}/src/LoggerConsole.cpp
+	AmuleApiConfig.cpp
+	Api.cpp
+	App.cpp
+	Auth.cpp
+	EventBus.cpp
+	EventDiff.cpp
+	HttpServer.cpp
+	Refresher.cpp
+	RefresherTick.cpp
+	StaticFs.cpp
+	State.cpp
+)
+
+if (WIN32)
+	target_sources (amuleapi
+		PRIVATE ${CMAKE_BINARY_DIR}/version.rc
+	)
+endif()
+
+# Console / daemon — never builds wx GUI bits.
+target_compile_definitions (amuleapi
+	PRIVATE wxUSE_GUI=0
+)
+
+target_include_directories (amuleapi
+	PRIVATE ${CMAKE_BINARY_DIR}
+	PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}
+	PRIVATE ${SRC_DIR}
+	PRIVATE ${Boost_INCLUDE_DIR}
+)
+
+target_link_libraries (amuleapi
+	PRIVATE ec
+	PRIVATE mulecommon
+	PRIVATE mulesocket
+	PRIVATE webcommon
+	PRIVATE wxWidgets::NET
+	PRIVATE ${Boost_LIBRARIES}
+)
+
+# Same gettext shim as amuleweb — _() in the CLI text needs libintl on
+# macOS / MinGW. Glibc bakes the symbols into libc, so the guard is a
+# noop there.
+if (ENABLE_NLS AND Intl_FOUND)
+	target_include_directories (amuleapi PRIVATE ${Intl_INCLUDE_DIRS})
+	target_link_libraries (amuleapi PRIVATE ${Intl_LIBRARIES})
+endif()
+
+if (HAVE_BFD)
+	target_link_libraries (amuleapi
+		PRIVATE ${LIBBFD}
+	)
+endif()
+
+# ExternalConnector.cpp pulls in libreadline when HAVE_LIBREADLINE is
+# defined at configure time (it's part of the readline-augmented TextShell
+# implementation amulecmd uses for tab completion). amuleapi never
+# enters TextShell, but the linker still resolves the references because
+# they live in unconditionally-emitted symbols inside the same TU.
+if (HAVE_LIBREADLINE)
+	target_link_libraries (amuleapi
+		PRIVATE ${READLINE_LIBRARIES}
+	)
+endif()
+
+if (APPLE)
+	# CoreServices / ApplicationServices — same set amuleweb links, used
+	# by wxStandardPaths::GetUserDataDir() on a .app bundle to look up
+	# Application Support/ correctly.
+	target_link_libraries (amuleapi
+		PRIVATE "-framework CoreServices"
+		PRIVATE "-framework ApplicationServices"
+	)
+endif()
+
+install (TARGETS amuleapi
+	RUNTIME DESTINATION bin
+)
+
+# Bundled static-frontend tree. Empty StaticRoot in amuleapi.conf keeps
+# the daemon API-only; setting it to ${CMAKE_INSTALL_DATADIR}/amule/
+# amuleapi-static makes the daemon serve this tree (placeholder
+# index.html out of the box — replace with a real frontend bundle in
+# place to start serving one).
+install (DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/static/
+	DESTINATION ${CMAKE_INSTALL_DATADIR}/amule/amuleapi-static
+)
diff --git a/src/webapi/EventBus.cpp b/src/webapi/EventBus.cpp
new file mode 100644
index 0000000000..fe1ae6c8c4
--- /dev/null
+++ b/src/webapi/EventBus.cpp
@@ -0,0 +1,180 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#include "EventBus.h"
+
+
+namespace webapi {
+
+
+// C++14 requires an out-of-class definition for static constexpr
+// members used by reference (test code may bind them through a
+// const auto& parameter). C++17 inlined that, but the project is
+// pinned to C++14.
+constexpr std::size_t CEventBus::kDefaultCapacity;
+constexpr std::size_t CEventBus::kMinCapacity;
+
+
+CEventBus::CEventBus(std::size_t capacity)
+	: m_capacity(capacity < kMinCapacity ? kMinCapacity : capacity)
+{
+}
+
+
+void CEventBus::Publish(const std::string &name, const std::string &data)
+{
+	Event ev;
+	ev.name = name;
+	ev.data = data;
+	{
+		std::lock_guard<std::mutex> g(m_mu);
+		// ID assignment INSIDE the lock. With fetch_add outside,
+		// two concurrent publishers can swap their lock-order vs
+		// their id-order: thread A gets id=N, thread B gets id=N+1,
+		// then thread B grabs the lock first and pushes id=N+1
+		// before thread A pushes id=N. The drainer then iterates
+		// the deque (which is publish order, NOT id order) and
+		// reports `id=N+1, id=N` — failing the strict-monotonicity
+		// invariant every subscriber depends on.
+		// Single-lock-section publish keeps fetch+push atomic.
+		ev.id = m_next_id.fetch_add(1, std::memory_order_relaxed);
+		if (m_ring.size() >= m_capacity) m_ring.pop_front();
+		m_ring.push_back(std::move(ev));
+	}
+	// notify_all so every blocked drainer wakes and races to its
+	// own copy-out. The mutex critical section is short (just walks
+	// the deque) so contention is negligible.
+	m_cv.notify_all();
+}
+
+
+void CEventBus::PublishBatch(
+	const std::vector<std::pair<std::string, std::string>> &events)
+{
+	if (events.empty()) return;
+	{
+		std::lock_guard<std::mutex> g(m_mu);
+		// Same id-monotonicity invariant as Publish: assign + push
+		// inside the lock. Doing the whole batch under one lock
+		// also collapses N notify_all wake-ups into one — the cold
+		// start tick on a 5K-download library used to fire 5K
+		// individual notify_all cycles inside the refresher loop
+		// (each going through every drainer's cv mutex), which
+		// dominated the tick's wall-clock.
+		for (const auto &kv : events) {
+			Event ev;
+			ev.name = kv.first;
+			ev.data = kv.second;
+			ev.id = m_next_id.fetch_add(1, std::memory_order_relaxed);
+			if (m_ring.size() >= m_capacity) m_ring.pop_front();
+			m_ring.push_back(std::move(ev));
+		}
+	}
+	m_cv.notify_all();
+}
+
+
+std::uint64_t CEventBus::Drain(std::uint64_t since_id,
+                               std::chrono::milliseconds timeout,
+                               std::vector<Event> &out)
+{
+	out.clear();
+	// Fast-fail on shutdown so a freshly-spawned SSE worker that
+	// raced past the IsShutdown poll doesn't block in wait_for.
+	if (m_shutdown.load(std::memory_order_acquire)) return since_id;
+	std::unique_lock<std::mutex> lk(m_mu);
+
+	// Quick path: any events with id > since_id already in ring?
+	auto has_newer = [&]() {
+		return m_shutdown.load(std::memory_order_acquire)
+		    || (!m_ring.empty() && m_ring.back().id > since_id);
+	};
+	if (!has_newer()) {
+		// Wait up to `timeout` for someone to publish OR for the
+		// shutdown latch to fire. wait_for returns no_timeout on a
+		// notify, timeout otherwise. We re-check the predicate
+		// either way.
+		m_cv.wait_for(lk, timeout, has_newer);
+	}
+
+	if (m_shutdown.load(std::memory_order_acquire)) return since_id;
+
+	std::uint64_t max_seen = since_id;
+	for (const auto &ev : m_ring) {
+		if (ev.id > since_id) {
+			out.push_back(ev);
+			if (ev.id > max_seen) max_seen = ev.id;
+		}
+	}
+	return max_seen;
+}
+
+
+std::uint64_t CEventBus::OldestId() const
+{
+	std::lock_guard<std::mutex> g(m_mu);
+	return m_ring.empty() ? 0 : m_ring.front().id;
+}
+
+
+std::uint64_t CEventBus::NewestId() const
+{
+	std::lock_guard<std::mutex> g(m_mu);
+	return m_ring.empty() ? 0 : m_ring.back().id;
+}
+
+
+void CEventBus::ResetForTest()
+{
+	{
+		std::lock_guard<std::mutex> g(m_mu);
+		m_ring.clear();
+		m_next_id.store(1, std::memory_order_release);
+		m_shutdown.store(false, std::memory_order_release);
+	}
+	m_cv.notify_all();
+}
+
+
+void CEventBus::Shutdown()
+{
+	// Latch the shutdown flag and broadcast. Drain callers wake on
+	// the cv either way (even with no events pending) and exit the
+	// predicate. notify_all under the lock so a drainer that's
+	// about to wait_for can't miss the wake.
+	{
+		std::lock_guard<std::mutex> g(m_mu);
+		m_shutdown.store(true, std::memory_order_release);
+	}
+	m_cv.notify_all();
+}
+
+
+bool CEventBus::IsShutdown() const
+{
+	return m_shutdown.load(std::memory_order_acquire);
+}
+
+
+}  // namespace webapi
diff --git a/src/webapi/EventBus.h b/src/webapi/EventBus.h
new file mode 100644
index 0000000000..a6ff317851
--- /dev/null
+++ b/src/webapi/EventBus.h
@@ -0,0 +1,156 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#ifndef WEBAPI_EVENT_BUS_H
+#define WEBAPI_EVENT_BUS_H
+
+#include <atomic>
+#include <chrono>
+#include <condition_variable>
+#include <cstdint>
+#include <deque>
+#include <mutex>
+#include <string>
+#include <vector>
+
+
+namespace webapi {
+
+
+// Event published over the SSE channel. Wire shape mirrors
+// `text/event-stream` per RFC 6202 §4: the SSE-emitter writes
+// `event: <name>\nid: <id>\ndata: <data>\n\n` for each event.
+//
+// `id` is monotonic across the bus's lifetime (uint64, never wraps
+// for any realistic uptime — 18 EH). It is NOT stable across
+// amuleapi restarts; the bus resets to 1 on each daemon start. The
+// `resync` event covers the restart case for SSE subscribers: when
+// a client reconnects with Last-Event-ID > the bus's current max,
+// it gets a resync event and re-GETs all affected collections.
+struct Event {
+	std::uint64_t id        = 0;
+	std::string   name;     // "download_added", "status_changed", etc.
+	std::string   data;     // JSON payload (typed per `name`)
+};
+
+
+// In-memory SSE event bus. One instance per amuleapi process; the
+// refresher publishes events as cache deltas surface and SSE
+// sessions drain them.
+//
+// **Concurrency:** all public methods are safe for any thread. The
+// refresher publishes from the wxApp thread (during a tick);
+// streaming-handler threads drain. Internal lock is a regular
+// std::mutex — drain operations only hold it long enough to
+// copy out the events they want, never across a wire write.
+//
+// **Capacity:** runtime-configured ring (see `[Streaming]/
+// EventBusRingCapacity` in amuleapi.conf; default 16 384). When the
+// buffer fills, the oldest event is dropped and clients whose
+// Last-Event-ID fell off the ring get a typed `resync` instead of a
+// partial replay. The default is sized for a cold-start tick on a
+// heavy node (5K downloads + 5K shared can publish ~10K `*_added`
+// in a single tick before any subscriber has had a chance to
+// drain); worst-case memory ≈ capacity × ~1 KB JSON payload, so
+// 16 384 ≈ 16 MB.
+class CEventBus {
+public:
+	// Compile-time floor + default. Capacity is settable at
+	// construction; values below kMinCapacity are clamped up to the
+	// floor. Floor exists so an operator can't accidentally
+	// effectively disable SSE replay by setting capacity=1.
+	static constexpr std::size_t kDefaultCapacity = 16384;
+	static constexpr std::size_t kMinCapacity     = 16;
+
+	CEventBus() : CEventBus(kDefaultCapacity) {}
+	explicit CEventBus(std::size_t capacity);
+
+	// Effective ring capacity actually in use (post-clamp).
+	std::size_t Capacity() const { return m_capacity; }
+
+	// Publish a new event. Assigns the next id and stores it. Wakes
+	// all blocked Drain* callers. Drop the oldest event if the ring
+	// is full.
+	void Publish(const std::string &name, const std::string &data);
+
+	// Batch-publish. One lock acquisition + one notify_all for the
+	// whole batch, vs N of each from per-event Publish loops. Used
+	// by the cold-start tick where a 5K-download library emits one
+	// `_added` per item — the per-item Publish was holding the
+	// refresher loop for tens of milliseconds (every notify_all
+	// goes through cv->mutex wake/sleep cycles on every drainer).
+	// Each (name, data) pair is treated identically to a Publish
+	// call: monotonic id assignment, evict-oldest if the ring fills.
+	void PublishBatch(
+		const std::vector<std::pair<std::string, std::string>> &events);
+
+	// Drain every event with `id > since_id` into `out`. Returns
+	// the highest id we found (== since_id if nothing new). Blocks
+	// up to `timeout` if there are no new events; returns early
+	// when something becomes available.
+	std::uint64_t Drain(std::uint64_t since_id,
+	                    std::chrono::milliseconds timeout,
+	                    std::vector<Event> &out);
+
+	// The id of the bus's oldest currently-stored event, or 0 if the
+	// bus is empty. Used by the Last-Event-ID reconnect path: if
+	// `Last-Event-ID < OldestId()` the client missed events that
+	// have already been evicted and should be sent `resync` instead
+	// of an empty replay.
+	std::uint64_t OldestId() const;
+
+	// The id of the most recently published event, or 0 if nothing
+	// has been published yet. The reconnect path uses this to
+	// compute "did I miss anything".
+	std::uint64_t NewestId() const;
+
+	// Reset the bus. Wakes any blocked drainers. Used by tests; not
+	// called from production code.
+	void ResetForTest();
+
+	// Atomically wake every blocked Drain caller and mark the bus as
+	// "shutting down". Subsequent Drain calls return immediately
+	// (with an empty out vector). Used by the shutdown path:
+	// detached SSE worker threads sit inside Drain() blocked on the
+	// 15 s heartbeat; without this they'd hold references to the
+	// dispatcher across its destruction → UAF. Latches once; idempotent.
+	void Shutdown();
+
+	// True if Shutdown() has been called. SSE worker loops poll this
+	// between Drain calls and exit cleanly.
+	bool IsShutdown() const;
+
+private:
+	const std::size_t                           m_capacity;
+	mutable std::mutex                          m_mu;
+	std::condition_variable                     m_cv;
+	std::deque<Event>                           m_ring;
+	std::atomic<std::uint64_t>                  m_next_id{1};
+	std::atomic<bool>                           m_shutdown{false};
+};
+
+
+}  // namespace webapi
+
+#endif // WEBAPI_EVENT_BUS_H
diff --git a/src/webapi/EventDiff.cpp b/src/webapi/EventDiff.cpp
new file mode 100644
index 0000000000..f08981fa12
--- /dev/null
+++ b/src/webapi/EventDiff.cpp
@@ -0,0 +1,660 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#include "EventDiff.h"
+
+#include "EventBus.h"
+
+#include <atomic>
+#include <cstdlib>
+#include <iostream>
+#include <sstream>
+#include <thread>
+
+
+namespace webapi {
+
+
+namespace {
+
+// Minimal JSON string escaper. JsonWriter (libwebcommon) is the
+// canonical formatter for response bodies, but the event-data
+// payloads we emit here are small and predictable — a few KB at
+// most — and keeping the diff path independent of CJsonWriter
+// avoids dragging wxString into the bus path. Quote-escape only the
+// characters JSON disallows: backslash, double-quote, and the C0
+// controls. Tab/CR/LF appear in amule log lines so we encode them
+// explicitly.
+std::string EscJson(const std::string &s)
+{
+	std::string out;
+	out.reserve(s.size() + 8);
+	for (unsigned char c : s) {
+		switch (c) {
+			case '\\': out += "\\\\"; break;
+			case '"':  out += "\\\""; break;
+			case '\b': out += "\\b";  break;
+			case '\f': out += "\\f";  break;
+			case '\n': out += "\\n";  break;
+			case '\r': out += "\\r";  break;
+			case '\t': out += "\\t";  break;
+			default:
+				if (c < 0x20) {
+					char buf[8];
+					std::snprintf(buf, sizeof(buf), "\\u%04x", c);
+					out += buf;
+				} else {
+					out += static_cast<char>(c);
+				}
+		}
+	}
+	return out;
+}
+
+
+// Each ToJson emits the SAME shape as the corresponding REST list-item
+// writer in Api.cpp (WriteDownloadObject / WriteSharedObject /
+// WriteServerObject / WriteClientObject / HandleStatus). The contract
+// is "an SSE _added/_updated event carries the full resource — clients
+// don't need to re-GET to see the moved counters". The matching Equal
+// functions below compare every field included here so any movement
+// fires `_updated`. If REST or SSE drifts in the future, the doc-
+// alignment check in run-all.sh phase11 should catch it.
+
+// download_* event payload — mirrors WriteDownloadObject (Api.cpp)
+// at the wire level. Reads the download sub-block of FileSnapshot.
+std::string ToJsonDownloadEvent(const FileSnapshot &f)
+{
+	std::ostringstream o;
+	o << "{"
+	  << "\"hash\":\"" << EscJson(f.hash) << "\""
+	  << ",\"name\":\"" << EscJson(f.name) << "\""
+	  << ",\"ed2k_link\":\"" << EscJson(f.ed2k_link) << "\""
+	  << ",\"size\":" << f.size
+	  << ",\"size_done\":" << f.download.size_done
+	  << ",\"size_xfer\":" << f.download.size_xfer
+	  << ",\"speed_bps\":" << f.download.speed_bps
+	  << ",\"status\":\"" << EscJson(f.download.status) << "\""
+	  << ",\"priority\":\"" << EscJson(f.priority) << "\""
+	  << ",\"priority_auto\":" << (f.download.priority_auto ? "true" : "false")
+	  << ",\"category\":" << f.download.category
+	  << ",\"sources\":{"
+	    << "\"total\":" << f.download.sources_total
+	    << ",\"not_current\":" << f.download.sources_not_current
+	    << ",\"transferring\":" << f.download.sources_transferring
+	    << ",\"a4af\":" << f.download.sources_a4af
+	    << "}"
+	  << ",\"progress\":{\"percent\":" << f.download.percent << "}"
+	  << "}";
+	return o.str();
+}
+
+
+// shared_* event payload — mirrors WriteSharedObject. Reads the
+// shared sub-block of FileSnapshot.
+std::string ToJsonSharedEvent(const FileSnapshot &f)
+{
+	std::ostringstream o;
+	o << "{"
+	  << "\"hash\":\"" << EscJson(f.hash) << "\""
+	  << ",\"name\":\"" << EscJson(f.name) << "\""
+	  << ",\"ed2k_link\":\"" << EscJson(f.ed2k_link) << "\""
+	  << ",\"size\":" << f.size
+	  << ",\"priority\":\"" << EscJson(f.priority) << "\""
+	  << ",\"complete_sources\":" << f.shared.complete_sources
+	  << ",\"xfer\":{\"session\":" << f.shared.xfer_session
+	    << ",\"total\":" << f.shared.xfer_total << "}"
+	  << ",\"requests\":{\"session\":" << f.shared.requests_session
+	    << ",\"total\":" << f.shared.requests_total << "}"
+	  << ",\"accepts\":{\"session\":" << f.shared.accepts_session
+	    << ",\"total\":" << f.shared.accepts_total << "}"
+	  << "}";
+	return o.str();
+}
+
+
+std::string ToJson(const ServerSnapshot &s)
+{
+	std::ostringstream o;
+	o << "{"
+	  << "\"ecid\":" << s.ecid
+	  << ",\"name\":\"" << EscJson(s.name) << "\""
+	  << ",\"description\":\"" << EscJson(s.description) << "\""
+	  << ",\"version\":\"" << EscJson(s.version) << "\""
+	  << ",\"address\":\"" << EscJson(s.address) << "\""
+	  << ",\"port\":" << s.port
+	  << ",\"users\":" << s.users
+	  << ",\"max_users\":" << s.max_users
+	  << ",\"files\":" << s.files
+	  << ",\"priority\":\"" << EscJson(s.priority) << "\""
+	  << ",\"ping_ms\":" << s.ping_ms
+	  << ",\"failed\":" << s.failed
+	  << ",\"static\":" << (s.is_static ? "true" : "false")
+	  << "}";
+	return o.str();
+}
+
+
+std::string ToJson(const ClientSnapshot &c)
+{
+	std::ostringstream o;
+	o << "{"
+	  << "\"client_ecid\":" << c.ecid
+	  << ",\"client_name\":\"" << EscJson(c.client_name) << "\""
+	  << ",\"user_hash\":\"" << EscJson(c.user_hash) << "\""
+	  << ",\"ip\":\"" << EscJson(c.ip) << "\""
+	  << ",\"port\":" << c.port
+	  << ",\"software\":\"" << EscJson(c.software) << "\""
+	  << ",\"software_version\":\"" << EscJson(c.software_version) << "\""
+	  << ",\"os_info\":\"" << EscJson(c.os_info) << "\""
+	  << ",\"upload_state\":\"" << EscJson(c.upload_state) << "\""
+	  << ",\"download_state\":\"" << EscJson(c.download_state) << "\""
+	  << ",\"ident_state\":\"" << EscJson(c.ident_state) << "\""
+	  << ",\"download_file_name\":\"" << EscJson(c.download_file_name) << "\""
+	  << ",\"upload_file_hash\":\"" << EscJson(c.upload_file_hash) << "\""
+	  << ",\"download_file_hash\":\"" << EscJson(c.download_file_hash) << "\""
+	  << ",\"xfer\":{"
+	    << "\"up_session\":" << c.xfer_up_session
+	    << ",\"down_session\":" << c.xfer_down_session
+	    << ",\"up_total\":" << c.xfer_up_total
+	    << ",\"down_total\":" << c.xfer_down_total
+	    << "}"
+	  << ",\"upload_speed_bps\":" << c.upload_speed_bps
+	  << ",\"download_speed_bps\":" << c.download_speed_bps
+	  << ",\"queue_waiting_position\":" << c.queue_waiting_position
+	  << ",\"remote_queue_rank\":" << c.remote_queue_rank
+	  << ",\"score\":" << c.score
+	  << ",\"obfuscation_status\":\"" << EscJson(c.obfuscation_status) << "\""
+	  << ",\"friend_slot\":" << (c.friend_slot ? "true" : "false")
+	  << "}";
+	return o.str();
+}
+
+
+// Status event payload mirrors the REST /status envelope nesting
+// (ed2k.*, kad.* including the kad.network rollup, speeds.*, queue.*,
+// plus the top-level ec_connected flag). Takes a triple because the
+// REST nesting groups data from StatusSnapshot AND KadSnapshot AND
+// the dashboard's ec_connected bit — all three are read in one
+// shared_lock by state.Dashboard() at the call site.
+std::string ToJsonStatusEvent(const StatusSnapshot &s,
+                              const KadSnapshot    &k,
+                              bool                  ec_connected)
+{
+	std::ostringstream o;
+	o << "{"
+	  << "\"ec_connected\":" << (ec_connected ? "true" : "false")
+	  << ",\"ed2k\":{"
+	    << "\"state\":\"" << EscJson(s.ed2k_state) << "\""
+	    << ",\"low_id\":" << (s.ed2k_lowid ? "true" : "false")
+	    << ",\"server_name\":\"" << EscJson(s.server_name) << "\""
+	    << ",\"server_ip\":\"" << EscJson(s.server_ip) << "\""
+	    << ",\"server_port\":" << s.server_port
+	    << "}"
+	  << ",\"kad\":{"
+	    << "\"state\":\"" << EscJson(s.kad_state) << "\""
+	    << ",\"firewalled\":" << (s.kad_firewalled ? "true" : "false")
+	    << ",\"network\":{"
+	      << "\"users\":" << k.users
+	      << ",\"files\":" << k.files
+	      << ",\"nodes\":" << k.nodes
+	      << "}"
+	    << "}"
+	  << ",\"speeds\":{"
+	    << "\"download_bps\":" << s.download_bps
+	    << ",\"upload_bps\":" << s.upload_bps
+	    << "}"
+	  << ",\"queue\":{"
+	    << "\"upload_queue_length\":" << s.ul_queue_len
+	    << ",\"total_source_count\":" << s.total_src_count
+	    << "}"
+	  << "}";
+	return o.str();
+}
+
+
+// Coarse equality — every field. For we treat any change as
+// "_updated" (emit the full new snapshot). v0.2 could introduce
+// per-field deltas if a real consumer reports wanting them.
+// Equal compares every field that ToJson emits. Any movement fires
+// `_updated`. Field sets here are the same as the matching ToJson
+// above; if one drifts from the other clients will see stale
+// values until the next ROW-level field changes.
+// download_* / shared_* event diffs compare the FIELDS THAT THE
+// CORRESPONDING ToJson emits, not the full FileSnapshot. The download
+// side ignores shared.* and is_shared, the shared side ignores
+// download.* and is_downloading — a tick that flips one role doesn't
+// fire the other role's _updated.
+//
+// ecid is in both JSON shapes; if amuled gets restarted while
+// amuleapi keeps running, the same hash will surface with a fresh
+// ECID, and clients keyed on ECID need the _updated to invalidate
+// their cached id.
+bool EqualDownload(const FileSnapshot &a, const FileSnapshot &b)
+{
+	return a.ecid == b.ecid && a.hash == b.hash && a.name == b.name
+	    && a.ed2k_link == b.ed2k_link
+	    && a.size == b.size
+	    && a.priority == b.priority
+	    && a.download.size_done == b.download.size_done
+	    && a.download.size_xfer == b.download.size_xfer
+	    && a.download.speed_bps == b.download.speed_bps
+	    && a.download.status    == b.download.status
+	    && a.download.priority_auto == b.download.priority_auto
+	    && a.download.category  == b.download.category
+	    && a.download.sources_total        == b.download.sources_total
+	    && a.download.sources_not_current  == b.download.sources_not_current
+	    && a.download.sources_transferring == b.download.sources_transferring
+	    && a.download.sources_a4af         == b.download.sources_a4af
+	    && a.download.percent  == b.download.percent;
+}
+bool EqualShared(const FileSnapshot &a, const FileSnapshot &b)
+{
+	return a.ecid == b.ecid && a.hash == b.hash && a.name == b.name
+	    && a.ed2k_link == b.ed2k_link
+	    && a.size == b.size
+	    && a.priority == b.priority
+	    && a.shared.complete_sources == b.shared.complete_sources
+	    && a.shared.xfer_session     == b.shared.xfer_session
+	    && a.shared.xfer_total       == b.shared.xfer_total
+	    && a.shared.requests_session == b.shared.requests_session
+	    && a.shared.requests_total   == b.shared.requests_total
+	    && a.shared.accepts_session  == b.shared.accepts_session
+	    && a.shared.accepts_total    == b.shared.accepts_total;
+}
+bool Equal(const ServerSnapshot &a, const ServerSnapshot &b)
+{
+	return a.name == b.name
+	    && a.description == b.description
+	    && a.version == b.version
+	    && a.address == b.address
+	    && a.port == b.port
+	    && a.users == b.users
+	    && a.max_users == b.max_users
+	    && a.files == b.files
+	    && a.priority == b.priority
+	    && a.ping_ms == b.ping_ms
+	    && a.failed == b.failed
+	    && a.is_static == b.is_static;
+}
+bool Equal(const ClientSnapshot &a, const ClientSnapshot &b)
+{
+	return a.client_name == b.client_name
+	    && a.user_hash == b.user_hash
+	    && a.ip == b.ip
+	    && a.port == b.port
+	    && a.software == b.software
+	    && a.software_version == b.software_version
+	    && a.os_info == b.os_info
+	    && a.upload_state == b.upload_state
+	    && a.download_state == b.download_state
+	    && a.ident_state == b.ident_state
+	    && a.download_file_name == b.download_file_name
+	    && a.upload_file_hash == b.upload_file_hash
+	    && a.download_file_hash == b.download_file_hash
+	    && a.xfer_up_session == b.xfer_up_session
+	    && a.xfer_down_session == b.xfer_down_session
+	    && a.xfer_up_total == b.xfer_up_total
+	    && a.xfer_down_total == b.xfer_down_total
+	    && a.upload_speed_bps == b.upload_speed_bps
+	    && a.download_speed_bps == b.download_speed_bps
+	    && a.queue_waiting_position == b.queue_waiting_position
+	    && a.remote_queue_rank == b.remote_queue_rank
+	    && a.score == b.score
+	    && a.obfuscation_status == b.obfuscation_status
+	    && a.friend_slot == b.friend_slot;
+}
+bool Equal(const StatusSnapshot &a, const StatusSnapshot &b)
+{
+	return a.ed2k_state == b.ed2k_state && a.kad_state == b.kad_state
+	    && a.ed2k_lowid == b.ed2k_lowid
+	    && a.kad_firewalled == b.kad_firewalled
+	    && a.server_name == b.server_name
+	    && a.server_ip == b.server_ip
+	    && a.server_port == b.server_port
+	    && a.download_bps == b.download_bps
+	    && a.upload_bps == b.upload_bps
+	    && a.ul_queue_len == b.ul_queue_len
+	    && a.total_src_count == b.total_src_count;
+}
+bool Equal(const KadSnapshot &a, const KadSnapshot &b)
+{
+	return a.users == b.users && a.files == b.files && a.nodes == b.nodes;
+}
+
+
+// Generic map-diff helper. Walks both old and new, emitting:
+//  - `<base>_removed` for keys in old missing from new (identity-only)
+//  - `<base>_added`   for keys in new missing from old (full ToJson)
+//  - `<base>_updated` for shared keys whose values differ (full ToJson)
+//
+// `removed_id_payload_fn` formats the identity-only `_removed` payload
+// — `{"hash": "..."}` for hash-keyed (downloads, shared) or
+// `{"ecid": N}` for ECID-keyed (servers, clients).
+//
+// Coalesced into one PublishBatch (one lock acquisition, one
+// notify_all) so a cold-start diff on a 5K-download library doesn't
+// fire 5K notify_all cycles inside the refresher loop.
+template <class Map, class IdentityFn>
+void DiffMap(CEventBus &bus, const std::string &base,
+             const Map &old_items, const Map &new_items,
+             IdentityFn removed_id_payload_fn)
+{
+	std::vector<std::pair<std::string, std::string>> batch;
+	batch.reserve(old_items.size() + new_items.size());
+	const std::string removed_name = base + "_removed";
+	const std::string added_name   = base + "_added";
+	const std::string updated_name = base + "_updated";
+	for (const auto &kv : old_items) {
+		if (new_items.find(kv.first) == new_items.end()) {
+			batch.emplace_back(removed_name,
+			                   removed_id_payload_fn(kv.second));
+		}
+	}
+	for (const auto &kv : new_items) {
+		const auto it = old_items.find(kv.first);
+		if (it == old_items.end()) {
+			batch.emplace_back(added_name, ToJson(kv.second));
+		} else if (!Equal(it->second, kv.second)) {
+			batch.emplace_back(updated_name, ToJson(kv.second));
+		}
+	}
+	bus.PublishBatch(batch);
+}
+
+
+// For hash-keyed file events emit removed payloads as
+// `{"hash":"..."}` so consumers can drop the cache entry without
+// needing the old object.
+std::string RemovedHashPayload(const FileSnapshot &f)
+{
+	return "{\"hash\":\"" + EscJson(f.hash) + "\"}";
+}
+// ECID-keyed types (servers / clients): same shape, ECID payload.
+std::string RemovedEcidPayload(const ServerSnapshot &s)
+{
+	std::ostringstream o;
+	o << "{\"ecid\":" << s.ecid << "}";
+	return o.str();
+}
+std::string RemovedEcidPayload(const ClientSnapshot &c)
+{
+	std::ostringstream o;
+	o << "{\"client_ecid\":" << c.ecid << "}";
+	return o.str();
+}
+
+
+// Build an ECID-keyed map from the vector view that CState exposes.
+// The cache's internal layout is std::map<ECID, Snapshot>; the public
+// accessor returns std::vector<Snapshot>. For diffing we want
+// random-access-by-ECID, so we lift it back into a map. Cheap — O(N)
+// with N typically <1000 per substruct.
+template <class Snap>
+std::map<std::uint32_t, Snap> ByEcid(const std::vector<Snap> &v)
+{
+	std::map<std::uint32_t, Snap> m;
+	for (const auto &x : v) m.emplace(x.ecid, x);
+	return m;
+}
+
+}  // namespace
+
+
+namespace {
+
+// Single-writer invariant: only the wxApp refresher tick mutates
+// LastSeenState + publishes diffs. Anything else (a future inline-
+// refresh-then-publish, a debug recompute, etc.) is a silent
+// concurrency bug — events get duplicated/dropped depending on
+// which order the threads landed. Capture the first caller's
+// thread id and abort hard on any subsequent caller from a
+// different thread. Hard-abort (not assert) so the check survives
+// -DNDEBUG and ships in every Release / RelWithDebInfo binary.
+std::atomic<std::thread::id> g_publisher_thread;
+
+void EnforceSinglePublisher()
+{
+	const std::thread::id self = std::this_thread::get_id();
+	std::thread::id expected;
+	if (g_publisher_thread.compare_exchange_strong(expected, self)) {
+		return;          // first caller — claimed it
+	}
+	if (expected == self) return;
+	std::cerr << "amuleapi: EmitDiffsAndUpdate called from two "
+	             "different threads; this breaks the single-writer "
+	             "invariant on LastSeenState and the EventBus.\n";
+	std::abort();
+}
+
+}  // namespace
+
+
+void EmitDiffsAndUpdate(CEventBus &bus,
+                        LastSeenState &prev,
+                        const CState &state)
+{
+	EnforceSinglePublisher();
+	// Snapshot the current state under its read locks. Each accessor
+	// takes the shared_timed_mutex shared, copies, and returns. For
+	// files we use the unfiltered view (Files() — not the role-filtered
+	// Downloads/Shared) so the diff below sees role-flag transitions:
+	// a file that flipped is_shared false→true on an existing ECID
+	// must fire `shared_added` even though it's been in the unified
+	// map all along.
+	auto new_files     = ByEcid(state.Files());
+	auto new_servers   = ByEcid(state.Servers());
+	auto new_clients   = ByEcid(state.Clients());
+	// Read the full dashboard for status_changed — the event payload
+	// mirrors the REST /status nested envelope which pulls from
+	// StatusSnapshot + KadSnapshot + ec_connected. Dashboard() takes
+	// the State lock once for all three, so the rollup is coherent
+	// (kad.network can't be from tick N+1 while ed2k.* is from tick
+	// N).
+	auto new_dashboard = state.Dashboard();
+	const StatusSnapshot &new_status = new_dashboard.status;
+	const KadSnapshot    &new_kad    = new_dashboard.kad;
+	const bool            new_ec     = new_dashboard.ec_connected;
+
+	// Files: role-flag-aware diff. download_* fires on is_downloading
+	// transitions; shared_* on is_shared transitions. A single tick
+	// can fire both for the same file (e.g. partfile becoming shared
+	// + receiving a stat update on the download side).
+	{
+		std::vector<std::pair<std::string, std::string>> batch;
+		batch.reserve(new_files.size());
+		const auto push = [&](const char *name,
+		                      const std::string &payload) {
+			batch.emplace_back(name, payload);
+		};
+		// _removed first — clients can tear down their cache slot
+		// before the _added/_updated for the same ECID lands.
+		for (const auto &kv : prev.files) {
+			const auto it = new_files.find(kv.first);
+			if (it == new_files.end()) {
+				if (kv.second.is_downloading) {
+					push("download_removed", RemovedHashPayload(kv.second));
+				}
+				if (kv.second.is_shared) {
+					push("shared_removed", RemovedHashPayload(kv.second));
+				}
+			} else {
+				if (kv.second.is_downloading && !it->second.is_downloading) {
+					push("download_removed", RemovedHashPayload(kv.second));
+				}
+				if (kv.second.is_shared && !it->second.is_shared) {
+					push("shared_removed", RemovedHashPayload(kv.second));
+				}
+			}
+		}
+		// _added / _updated — gate by role flag transition vs the
+		// previous tick's is_downloading / is_shared value.
+		for (const auto &kv : new_files) {
+			const auto it = prev.files.find(kv.first);
+			const bool was_downloading = (it != prev.files.end()
+			                              && it->second.is_downloading);
+			const bool was_shared      = (it != prev.files.end()
+			                              && it->second.is_shared);
+			if (kv.second.is_downloading) {
+				if (!was_downloading) {
+					push("download_added", ToJsonDownloadEvent(kv.second));
+				} else if (!EqualDownload(it->second, kv.second)) {
+					push("download_updated", ToJsonDownloadEvent(kv.second));
+				}
+			}
+			if (kv.second.is_shared) {
+				if (!was_shared) {
+					push("shared_added", ToJsonSharedEvent(kv.second));
+				} else if (!EqualShared(it->second, kv.second)) {
+					push("shared_updated", ToJsonSharedEvent(kv.second));
+				}
+			}
+		}
+		bus.PublishBatch(batch);
+	}
+	DiffMap(bus, "server", prev.servers, new_servers,
+		[](const ServerSnapshot &s) {
+			return RemovedEcidPayload(s);
+		});
+	DiffMap(bus, "client", prev.clients, new_clients,
+		[](const ClientSnapshot &c) {
+			return RemovedEcidPayload(c);
+		});
+
+	// /status: one event when anything in the dashboard envelope
+	// changes (StatusSnapshot fields OR Kad network rollup OR
+	// ec_connected). Cold-start gates on `status_initialised` so we
+	// don't blast a status_changed on the very first tick (SSE
+	// subscribers already see the current state via REST; the
+	// *change* events are what they're here for).
+	if (!prev.status_initialised) {
+		bus.Publish("status_changed",
+			ToJsonStatusEvent(new_status, new_kad, new_ec));
+		prev.status_initialised = true;
+	} else if (!Equal(prev.status, new_status)
+	        || !Equal(prev.kad, new_kad)
+	        || prev.ec_connected != new_ec) {
+		bus.Publish("status_changed",
+			ToJsonStatusEvent(new_status, new_kad, new_ec));
+	}
+
+	// Snapshot the new state for next tick's diff baseline.
+	prev.files        = std::move(new_files);
+	prev.servers      = std::move(new_servers);
+	prev.clients      = std::move(new_clients);
+	prev.status       = new_status;
+	prev.kad          = new_kad;
+	prev.ec_connected = new_ec;
+
+	// Search events. `search_result_added` per new ECID in the results
+	// map; `search_progress` on any percent change while running and on
+	// the running→finished edge. The finished frame (state="finished",
+	// percent=100) is just the terminal search_progress — there is no
+	// separate search_finished event. The refresher's state machine
+	// (AdvanceSearchProgress) drives both — POST /search seeds the active
+	// flag; subsequent ticks either grow the results map, advance the
+	// percent, or flip complete. First tick after MarkSearchStarted
+	// bootstraps the baseline so we don't double-emit on first observation.
+	{
+		const auto search_now = ByEcid(state.Search());
+		const auto progress_now = state.SearchProgress();
+		if (!prev.search_initialised) {
+			prev.search             = search_now;
+			prev.search_complete    = progress_now.complete;
+			prev.search_percent     = progress_now.percent;
+			prev.search_initialised = true;
+		} else {
+			// New result entries.
+			for (const auto &kv : search_now) {
+				if (prev.search.find(kv.first) == prev.search.end()) {
+					std::ostringstream payload;
+					// Byte-for-byte identical to WriteSearchObject (Api.cpp):
+					// sources is a nested {total, complete} object, matching
+					// the /search/results[] entry rather than flattening it.
+					payload << "{\"hash\":\"" << EscJson(kv.second.hash) << "\""
+					        << ",\"name\":\"" << EscJson(kv.second.name) << "\""
+					        << ",\"size\":" << kv.second.size
+					        << ",\"sources\":{\"total\":" << kv.second.source_count
+					        << ",\"complete\":" << kv.second.complete_source_count << "}"
+					        << ",\"already_have\":"
+					        << (kv.second.already_have ? "true" : "false")
+					        << ",\"rating\":" << static_cast<int>(kv.second.rating)
+					        << "}";
+					bus.Publish("search_result_added", payload.str());
+				}
+			}
+			// search_progress: a percent change while running, or the
+			// running→finished edge (complete false→true). MarkSearchStarted
+			// resets complete=false + percent=0 so a new search after a
+			// previous completion gets fresh edges.
+			const bool finished_edge = progress_now.complete && !prev.search_complete;
+			const bool percent_moved = progress_now.percent != prev.search_percent;
+			if (finished_edge || percent_moved) {
+				std::ostringstream payload;
+				payload << "{\"state\":\""
+				        << (progress_now.complete ? "finished" : "running") << "\""
+				        << ",\"percent\":" << progress_now.percent
+				        << ",\"results\":" << search_now.size()
+				        << ",\"kind\":\"" << EscJson(progress_now.kind) << "\""
+				        << "}";
+				bus.Publish("search_progress", payload.str());
+			}
+			prev.search          = std::move(search_now);
+			prev.search_complete = progress_now.complete;
+			prev.search_percent  = progress_now.percent;
+		}
+	}
+
+	// log_appended. CState::AmuleLog() is append-only
+	// (CState.cpp:142-151) so a strictly-increasing size means the
+	// refresher just appended the tail. First tick records the
+	// size baseline silently — clients GET /api/v0/logs/amule for
+	// the historical buffer; the event channel is for live tail
+	// only. A truncation (size decreased) silently resyncs the
+	// counter; the only path that truncates today is a future
+	// `DELETE /logs/amule` mutation, and clients refetch on that
+	// regardless.
+	const auto amule_log = state.AmuleLog();
+	if (!prev.amule_log_initialised) {
+		prev.amule_log_count = amule_log.size();
+		prev.amule_log_initialised = true;
+	} else if (amule_log.size() < prev.amule_log_count) {
+		prev.amule_log_count = amule_log.size();
+	} else if (amule_log.size() > prev.amule_log_count) {
+		std::ostringstream payload;
+		payload << "{\"lines\":[";
+		bool first = true;
+		for (std::size_t i = prev.amule_log_count; i < amule_log.size(); ++i) {
+			if (!first) payload << ",";
+			first = false;
+			payload << "\"" << EscJson(amule_log[i]) << "\"";
+		}
+		payload << "]}";
+		bus.Publish("log_appended", payload.str());
+		prev.amule_log_count = amule_log.size();
+	}
+}
+
+
+}  // namespace webapi
diff --git a/src/webapi/EventDiff.h b/src/webapi/EventDiff.h
new file mode 100644
index 0000000000..7fffc142ac
--- /dev/null
+++ b/src/webapi/EventDiff.h
@@ -0,0 +1,108 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#ifndef WEBAPI_EVENT_DIFF_H
+#define WEBAPI_EVENT_DIFF_H
+
+#include "State.h"
+
+#include <map>
+#include <cstdint>
+
+
+namespace webapi {
+
+
+class CEventBus;
+
+
+// One "last seen" snapshot of all the substructs we publish events
+// for. Owned by CamuleapiApp; mutated AFTER each successful tick by
+// `EmitDiffsAndUpdate`. The first tick fires `_added` for every alive
+// entry (cold start); subsequent ticks fire only the deltas.
+struct LastSeenState {
+	// `files` mirrors CState::m_files (unified ECID-keyed map with
+	// `is_downloading` / `is_shared` flags). Role-flag transitions
+	// false→true emit the corresponding `_added` event, true→false
+	// the `_removed`; a file may participate in both views and emit
+	// both event families.
+	std::map<std::uint32_t, FileSnapshot>     files;
+	std::map<std::uint32_t, ServerSnapshot>   servers;
+	std::map<std::uint32_t, ClientSnapshot>   clients;
+	// Status event payload mirrors the REST /status envelope, which
+	// pulls from THREE sources (StatusSnapshot + KadSnapshot +
+	// ec_connected flag). All three must be diffed against the prior
+	// tick to decide whether to fire `status_changed`.
+	StatusSnapshot                            status;
+	KadSnapshot                               kad;
+	bool                                      ec_connected = false;
+	bool                                      status_initialised = false;
+
+	// log-tail tracking for the `log_appended` event.
+	// `amule_log_count` is the size of `state.AmuleLog()` at the
+	// previous tick. When the vector grows, the new tail is
+	// `log[amule_log_count .. new_size)` and we publish it.
+	// First-tick cold-start is gated by `amule_log_initialised` so
+	// we don't dump every historical line as one event — clients
+	// can GET /api/v0/logs/amule for the history.
+	std::size_t                               amule_log_count = 0;
+	bool                                      amule_log_initialised = false;
+
+	// Search-events baseline. Diffed against state.Search() +
+	// state.SearchProgress() each tick. New ECIDs → search_result_added;
+	// a percent change or the running→finished edge → search_progress
+	// (the terminal frame, state="finished", supersedes the old
+	// standalone search_finished event).
+	std::map<std::uint32_t, SearchResult>     search;
+	bool                                      search_complete   = false;
+	std::uint32_t                             search_percent    = 0;
+	bool                                      search_initialised = false;
+};
+
+
+// Walk every (old vs current) substruct, publish typed events for
+// each delta, then overwrite `prev` with the current snapshot so the
+// next tick diffs against the freshest baseline.
+//
+// Wire event names: download_{added,updated,removed},
+// shared_{added,updated,removed}, server_{added,updated,removed},
+// client_{added,updated,removed}, status_changed.
+//
+// `_added` / `_updated` payload: the full snapshot object (matches
+// the REST list-item shape byte-for-byte; clients overwrite their
+// cache slot from the new object).
+// `_removed` payload: `{"ecid": N}` for ECID-keyed types,
+// `{"hash": "..."}` for hash-keyed (downloads + shared).
+// `status_changed` payload: the nested REST /status envelope
+// (ed2k.*, kad.* with kad.network rollup, speeds.*, queue.*, plus
+// top-level ec_connected). Pulled from state.Dashboard() so all
+// three pieces stay consistent within a tick.
+void EmitDiffsAndUpdate(CEventBus &bus,
+                        LastSeenState &prev,
+                        const CState &state);
+
+
+}  // namespace webapi
+
+#endif // WEBAPI_EVENT_DIFF_H
diff --git a/src/webapi/HttpServer.cpp b/src/webapi/HttpServer.cpp
new file mode 100644
index 0000000000..ada1015538
--- /dev/null
+++ b/src/webapi/HttpServer.cpp
@@ -0,0 +1,749 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#include "HttpServer.h"
+
+#include "JsonWriter.h"
+
+#include <wx/string.h>
+
+#include <boost/asio/io_context.hpp>
+#include <boost/asio/ip/tcp.hpp>
+#include <boost/asio/strand.hpp>
+#include <boost/asio/write.hpp>
+#include <boost/beast/core.hpp>
+#include <boost/beast/http.hpp>
+#include <boost/beast/version.hpp>
+#include <boost/optional.hpp>
+
+#include <atomic>
+#include <cassert>
+#include <chrono>
+#include <iostream>
+#include <memory>
+#include <mutex>
+#include <sstream>
+#include <thread>
+#include <utility>
+
+
+namespace beast = boost::beast;
+namespace http  = boost::beast::http;
+namespace asio  = boost::asio;
+using tcp       = boost::asio::ip::tcp;
+
+
+namespace {
+
+// Per-connection session. Reads one request, hands it to the user
+// handler, writes the response, closes. No keep-alive — the API
+// surface is too small to benefit, and the one-shot model keeps the
+// state machine trivially auditable. If the streaming_resolver
+// matches the parsed request, the session takes a different path:
+// writes the response head and runs the streaming handler on a
+// worker thread, which can push chunks indefinitely via the Writer
+// interface until the handler returns or the peer disconnects.
+//
+// Process-wide cap on concurrent SSE subscribers. Each session
+// spawns one OS thread, so without a cap a non-loopback bind turns
+// the thread-per-connection model into a DoS amplifier. The cap is
+// sized for the single-operator dashboard pattern: a handful of
+// browser tabs + the odd shell script. Refused sessions get
+// `503 Service Unavailable` + a `Retry-After` hint inside the
+// streaming dispatch path before the worker thread is created.
+constexpr int kMaxConcurrentStreamingSessions = 32;
+std::atomic<int> g_streaming_session_count{0};
+
+class Session;
+
+// Live SSE session registry. Listener::Stop walks this on shutdown
+// to cancel each session's socket I/O — without it, a worker
+// blocked in a synchronous Beast write to a slow peer never sees
+// the io_context.stop() and the daemon hangs forever on exit.
+// weak_ptrs so dead sessions self-clean.
+std::mutex g_live_streams_mu;
+std::vector<std::weak_ptr<Session>> g_live_streams;
+
+class Session : public std::enable_shared_from_this<Session> {
+public:
+	Session(tcp::socket socket,
+	        CHttpServer::Handler handler,
+	        CHttpServer::StreamingResolver streaming_resolver,
+	        CHttpServer::StreamingHandler  streaming_handler,
+	        CHttpServer::StreamingPreflight streaming_preflight)
+		: m_stream(std::move(socket)),
+		  m_handler(std::move(handler)),
+		  m_streaming_resolver(std::move(streaming_resolver)),
+		  m_streaming_handler(std::move(streaming_handler)),
+		  m_streaming_preflight(std::move(streaming_preflight))
+	{}
+
+	~Session()
+	{
+		// Worker captures `shared_from_this()` and sets
+		// `m_worker_exited` true on the way out (via the RAII
+		// WorkerExitMarker below). By the time this dtor runs the
+		// last ref must have been dropped, so the worker must have
+		// exited; join() from inside the worker's own call stack
+		// would deadlock, detach() is safe.
+		//
+		// Hand-rolled if + std::abort instead of assert() so the
+		// invariant is enforced in Release too (NDEBUG strips
+		// assert).
+		if (m_stream_worker.joinable()) {
+			if (!m_worker_exited.load(std::memory_order_acquire)) {
+				std::cerr << "amuleapi: FATAL Session dtor reached "
+				             "with worker still running\n";
+				std::abort();
+			}
+			m_stream_worker.detach();
+		}
+		// Release the session slot. Decrement only fires if we
+		// actually acquired one (DispatchStreaming sets the flag).
+		if (m_session_slot_held) {
+			g_streaming_session_count.fetch_sub(
+				1, std::memory_order_acq_rel);
+		}
+	}
+
+	void Start() { DoRead(); }
+
+	// Called by Listener::Stop from a foreign thread to cancel any
+	// in-flight Beast write. Posts the close onto the stream's own
+	// executor so we don't race the worker thread's last write —
+	// boost::asio::tcp::socket is NOT thread-safe outside its
+	// strand. The post is fire-and-forget; we don't wait for the
+	// close to complete. The worker's writer.Alive() check picks up
+	// the dead m_stream_alive flag, returns, and the session's last
+	// shared_ptr ref drops, triggering destruction.
+	void RequestCancel()
+	{
+		// Atomic flip first so writer.Alive() observes the cancel
+		// even if the strand-posted close is delayed.
+		m_stream_alive.store(false, std::memory_order_release);
+		auto self = shared_from_this();
+		boost::asio::post(m_stream.get_executor(), [self]{
+			beast::error_code ec;
+			beast::get_lowest_layer(self->m_stream).socket().close(ec);
+		});
+	}
+
+private:
+	void DoRead()
+	{
+		// Reset the parser each request — without it, calling DoRead a
+		// second time on the same stream blocks forever with a partial
+		// state. only reads one request, but leaving the reset
+		// in keeps the read loop forward-compatible if keep-alive is
+		// turned on later.
+		m_parser.emplace();
+		// 1 MiB request cap — bigger than any sensible REST POST body
+		// (login JSON is ~64 bytes, etc.) but well under "someone is
+		// trying to exhaust memory by upload-pumping us".
+		m_parser->body_limit(1024 * 1024);
+		// 16 KiB header cap. Beast's default header_limit varies
+		// across versions (8 KiB in current upstream, larger on
+		// older releases). A drip-feed attacker who slowly streams
+		// header lines can otherwise grow the flat_buffer until the
+		// 10 s read timeout catches them — but that's 10 s × pool
+		// of concurrent peers. Cap headers explicitly so the
+		// per-peer memory ceiling is fixed regardless of upstream
+		// defaults: 16 KiB is well over any legitimate request
+		// (Authorization + a few Accept headers is < 2 KiB) and
+		// catches the drip-feed within ~1 KiB instead of ~MB.
+		m_parser->header_limit(16 * 1024);
+		// 10 s read timeout. amuleapi runs against localhost/LAN; a
+		// real client never takes 10 s to send a 1 KiB request.
+		m_stream.expires_after(std::chrono::seconds(10));
+
+		auto self = shared_from_this();
+		http::async_read(m_stream, m_buffer, *m_parser,
+			[self](beast::error_code ec, std::size_t bytes) {
+				(void)bytes;
+				if (ec == http::error::end_of_stream) {
+					self->DoClose();
+					return;
+				}
+				if (ec) {
+					// Read error (timeout, peer close, framing error) —
+					// stay quiet. amuleapi-side log noise from health-
+					// check probes ("000 errors are normal" in our
+					// curl-tests README) isn't worth the line per
+					// connection.
+					self->DoClose();
+					return;
+				}
+				self->Dispatch();
+			});
+	}
+
+	void Dispatch()
+	{
+		const auto &req = m_parser->get();
+
+		CHttpServer::Request r;
+		r.method = std::string(req.method_string());
+		r.target = std::string(req.target());
+		r.body   = req.body();
+		for (const auto &h : req) {
+			r.headers.emplace(std::string(h.name_string()),
+			                  std::string(h.value()));
+		}
+		// Remote endpoint for rate-limiting. `.address()` returns a
+		// boost::asio::ip::address which `.to_string()`-es to the
+		// canonical IPv4 / IPv6 form ("192.0.2.1", "::1", "fe80::%lo0"...).
+		// Wrapped in an error_code overload so a half-closed socket
+		// doesn't throw — empty `remote_addr` falls through to "no
+		// per-IP bucket" in the rate limiter, which is the safe default.
+		{
+			beast::error_code ec;
+			const auto ep = m_stream.socket().remote_endpoint(ec);
+			if (!ec) r.remote_addr = ep.address().to_string();
+		}
+
+		// streaming dispatch. The streaming_resolver is
+		// invoked synchronously and short-circuits the standard
+		// request→response→close path when it returns true.
+		if (m_streaming_resolver && m_streaming_handler
+		    && m_streaming_resolver(r)) {
+			DispatchStreaming(std::move(r));
+			return;
+		}
+
+		CHttpServer::Response resp;
+		try {
+			resp = m_handler(r);
+		} catch (const std::exception &e) {
+			// Handler exceptions become 500s; body shape matches the
+			// rest of the error contract.
+			//
+			// Info-disclosure: e.what() can carry caller-supplied
+			// bytes (picojson echoes the offending input character;
+			// a future header-driven throw could reflect
+			// Authorization or Cookie fragments). Keep the body
+			// generic; log detail to stderr.
+			std::cerr << "amuleapi: 500 from handler: " << e.what() << "\n";
+			resp.status       = 500;
+			resp.content_type = "application/json";
+			resp.body =
+				"{\"error\":{\"code\":\"internal\","
+				"\"message\":\"internal server error\"}}";
+		}
+
+		WriteResponse(std::move(resp));
+	}
+
+
+	// Streaming path. Writes the response head, then spawns a worker
+	// thread for the streaming handler. Session stays alive across
+	// the worker via the `shared_from_this()` capture; when the
+	// worker exits, the lambda releases the last ref and Session
+	// destructs (joining a thread that has already exited, a no-op).
+	//
+	// Short 503 for concurrent-session cap + other exhaustion paths.
+	void WriteCapRefusal()
+	{
+		CHttpServer::Response refused;
+		refused.status       = 503;
+		refused.content_type = "application/json";
+		refused.headers["Retry-After"] = "10";
+		refused.body =
+			"{\"error\":{\"code\":\"sessions_exhausted\","
+			"\"message\":\"too many concurrent streaming sessions; "
+			"retry in a few seconds\"}}";
+		WriteResponse(std::move(refused));
+	}
+
+	void DispatchStreaming(CHttpServer::Request r)
+	{
+		// Preflight runs synchronously on the I/O thread BEFORE the
+		// slot is claimed and BEFORE a worker thread is spawned. If
+		// it rejects (returns a Response), unauthenticated peers
+		// can't tie up a streaming slot for the read-timeout window:
+		// 32 unauth TCP holds × 10 s read timeout = a 320-session-
+		// second pool stall. With preflight, an unauth request
+		// burns one short HTTP exchange and goes away. Empty
+		// preflight (default) preserves the prior contract.
+		if (m_streaming_preflight) {
+			boost::optional<CHttpServer::Response> rej =
+				m_streaming_preflight(r);
+			if (rej) {
+				WriteResponse(std::move(*rej));
+				return;
+			}
+		}
+
+		// Acquire a session slot before doing any thread-spawn or
+		// long-lived work. fetch_add returns the OLD value, so we
+		// hold the slot iff that old value was strictly below the
+		// cap. Otherwise we roll back and refuse the connection.
+		const int prior_count = g_streaming_session_count.fetch_add(
+			1, std::memory_order_acq_rel);
+		if (prior_count >= kMaxConcurrentStreamingSessions) {
+			g_streaming_session_count.fetch_sub(
+				1, std::memory_order_acq_rel);
+			WriteCapRefusal();
+			return;
+		}
+		m_session_slot_held = true;
+		// Disable read timeout — SSE connections are long-lived.
+		m_stream.expires_never();
+		m_stream_alive.store(true, std::memory_order_release);
+
+		// Register the session so Listener::Stop can cancel its
+		// socket on shutdown. A worker blocked inside a synchronous
+		// Beast write to a slow peer otherwise pins the daemon at
+		// exit — the io_context.stop() doesn't unblock a write
+		// already in flight. Closing the underlying socket from
+		// outside makes the write fail with EPIPE and the worker
+		// returns to its writer.Alive() check, exits, releases the
+		// last ref.
+		{
+			std::lock_guard<std::mutex> g(g_live_streams_mu);
+			g_live_streams.emplace_back(shared_from_this());
+		}
+
+		// Spawn the worker thread that runs the streaming handler.
+		// The worker captures `self` so the Session stays alive
+		// across its run, and references to the head out-params (held
+		// on the heap so the SocketWriter can read them at first-
+		// write time).
+		auto handler = m_streaming_handler;
+		auto self    = shared_from_this();
+		// Head data — owned by the worker thread, referenced by the
+		// SocketWriter (via SocketWriter::HeadData). Defaults set
+		// here; handler can overwrite before calling writer.Write
+		// the first time.
+		auto head = std::make_shared<SocketWriter::HeadData>();
+		head->headers["Cache-Control"] = "no-cache";
+		head->headers["Connection"]    = "keep-alive";
+
+		auto writer = std::make_shared<SocketWriter>(self, head);
+
+		// One std::thread per streaming session — cheap at expected
+		// scale (1–5 concurrent SSE subscribers) and keeps the drain
+		// synchronous so `since_id` ordering is trivial.
+		//
+		// **The default `BindAddress=127.0.0.1` is load-bearing.**
+		// Non-loopback bind + unauth peer = thread-per-connection DoS
+		// amplifier. PreflightEvents (auth before slot claim, before
+		// thread spawn) bounds pre-auth cost to one HTTP exchange.
+		m_stream_worker = std::thread([self, handler, writer, head,
+		                               r = std::move(r)]() mutable {
+			// RAII guard: tip the worker-exited flag on EVERY exit
+			// path out of this lambda, including a future refactor
+			// that adds an early `return` after the catch block.
+			// The Session destructor's std::abort() guard only
+			// fires if this flag is true, so missing the flip on
+			// some path would tear down a still-running thread.
+			struct WorkerExitMarker {
+				std::shared_ptr<Session> s;
+				~WorkerExitMarker() {
+					s->m_worker_exited.store(true,
+						std::memory_order_release);
+				}
+			} marker{self};
+			try {
+				handler(r, *writer,
+				        head->status, head->content_type,
+				        head->headers);
+			} catch (const std::exception &) {
+				// Streaming handler exceptions are silent — close
+				// quietly.
+			}
+			// If the handler returned without writing anything (e.g.
+			// auth-rejected on a HEAD probe), still emit the head so
+			// the client sees the right status code.
+			writer->EnsureHeadWritten();
+			self->DoClose();
+			// `marker` runs here, flipping m_worker_exited and
+			// dropping `self` only AFTER the flag is set — so the
+			// dtor's check observes the post-exit state.
+		});
+	}
+
+	// Per-streaming-session Writer that marshals writes onto the
+	// socket. Defers writing the HTTP response head until the first
+	// Write call — that's when the streaming handler has finalised
+	// status / content_type / headers via the out-params we pass it.
+	class SocketWriter : public CHttpServer::Writer {
+	public:
+		struct HeadData {
+			unsigned    status       = 200;
+			std::string content_type = "text/event-stream";
+			std::map<std::string, std::string> headers;
+		};
+
+		SocketWriter(std::shared_ptr<Session> session,
+		             std::shared_ptr<Session::SocketWriter::HeadData> head)
+			: m_session(std::move(session)),
+			  m_head(std::move(head)) {}
+
+		bool Write(const std::string &chunk) override
+		{
+			if (!m_session->m_stream_alive.load(std::memory_order_acquire)) {
+				return false;
+			}
+			if (!EnsureHeadWritten()) return false;
+
+			// SSE wire shape uses chunked transfer encoding; each
+			// "chunk" written here is a single HTTP/1.1 chunk frame:
+			//  <hex-size-of-chunk>\r\n<chunk-bytes>\r\n
+			//
+			// Zero-length chunks would terminate the message (per
+			// RFC 7230 §4.1) so we skip them — the heartbeat path
+			// always passes at least ": keepalive\n\n" anyway.
+			if (chunk.empty()) return true;
+			std::ostringstream framed;
+			framed << std::hex << chunk.size() << "\r\n"
+			       << chunk << "\r\n";
+			const std::string out = framed.str();
+
+			std::lock_guard<std::mutex> g(m_session->m_socket_mu);
+			beast::error_code ec;
+			asio::write(m_session->m_stream.socket(),
+				asio::buffer(out), ec);
+			if (ec) {
+				m_session->m_stream_alive.store(false,
+					std::memory_order_release);
+				return false;
+			}
+			return true;
+		}
+
+		bool Alive() const override
+		{
+			return m_session->m_stream_alive.load(std::memory_order_acquire);
+		}
+
+		// Idempotent: writes the head once, on first call. Returns
+		// false if the underlying socket write failed.
+		//
+		// We build the head as raw bytes rather than going through
+		// Beast's response<empty_body> + prepare_payload() — that
+		// path emits `Content-Length: 0` and silently strips our
+		// `Transfer-Encoding: chunked`, which forecloses the
+		// streaming body that the SSE channel needs. Direct
+		// string-formatted head dodges the conflict and is short
+		// enough to audit at a glance.
+		bool EnsureHeadWritten()
+		{
+			if (m_head_written.exchange(true, std::memory_order_acq_rel)) {
+				return true;
+			}
+			std::ostringstream head;
+			head << "HTTP/1.1 " << m_head->status << " ";
+			switch (m_head->status) {
+				case 200: head << "OK"; break;
+				case 401: head << "Unauthorized"; break;
+				case 403: head << "Forbidden"; break;
+				case 404: head << "Not Found"; break;
+				default:  head << "OK"; break;
+			}
+			head << "\r\n";
+			head << "Server: amuleapi\r\n";
+			head << "Content-Type: " << m_head->content_type << "\r\n";
+			// Chunked when the body will actually stream — i.e.
+			// success path. Error responses (401 / 403) are single-
+			// shot: the handler emits one chunk-as-error-body then
+			// returns, and we'd rather close-on-FIN than dangle a
+			// chunked half-message. For those we omit
+			// Transfer-Encoding so the response simply terminates
+			// at connection close.
+			const bool chunked = (m_head->status >= 200
+			                      && m_head->status < 300);
+			if (chunked) {
+				head << "Transfer-Encoding: chunked\r\n";
+			}
+			for (const auto &kv : m_head->headers) {
+				head << kv.first << ": " << kv.second << "\r\n";
+			}
+			head << "\r\n";
+			const std::string head_bytes = head.str();
+
+			std::lock_guard<std::mutex> g(m_session->m_socket_mu);
+			beast::error_code ec;
+			asio::write(m_session->m_stream.socket(),
+				asio::buffer(head_bytes), ec);
+			if (ec) {
+				m_session->m_stream_alive.store(false,
+					std::memory_order_release);
+				return false;
+			}
+			return true;
+		}
+
+	private:
+		std::shared_ptr<Session> m_session;
+		std::shared_ptr<HeadData> m_head;
+		std::atomic<bool>        m_head_written{false};
+	};
+
+	void WriteResponse(CHttpServer::Response &&resp)
+	{
+		m_response.emplace();
+		m_response->version(11);
+		m_response->result(resp.status);
+		m_response->set(http::field::server, "amuleapi");
+		m_response->set(http::field::content_type, resp.content_type);
+		for (const auto &h : resp.headers) {
+			m_response->set(h.first, h.second);
+		}
+		m_response->body() = std::move(resp.body);
+		m_response->prepare_payload();
+
+		auto self = shared_from_this();
+		http::async_write(m_stream, *m_response,
+			[self](beast::error_code ec, std::size_t) {
+				(void)ec;
+				self->DoClose();
+			});
+	}
+
+	void DoClose()
+	{
+		// If we were streaming, write the chunked-encoding terminator
+		// (0-size chunk) before shutting down. Idempotent — if the
+		// peer already closed, the write fails silently.
+		if (m_stream_alive.exchange(false, std::memory_order_acq_rel)) {
+			std::lock_guard<std::mutex> g(m_socket_mu);
+			beast::error_code ec;
+			asio::write(m_stream.socket(),
+				asio::buffer(std::string("0\r\n\r\n")), ec);
+		}
+		beast::error_code ec;
+		m_stream.socket().shutdown(tcp::socket::shutdown_send, ec);
+		// `ec` deliberately discarded — peer may have already gone
+		// away.
+	}
+
+	beast::tcp_stream                                m_stream;
+	beast::flat_buffer                               m_buffer{8192};
+	boost::optional<http::request_parser<http::string_body>> m_parser;
+	boost::optional<http::response<http::string_body>> m_response;
+	CHttpServer::Handler                             m_handler;
+
+	// streaming state.
+	CHttpServer::StreamingResolver  m_streaming_resolver;
+	CHttpServer::StreamingHandler   m_streaming_handler;
+	CHttpServer::StreamingPreflight m_streaming_preflight;
+	std::atomic<bool>               m_stream_alive{false};
+	// Set true by the worker on exit. The Session destructor asserts
+	// on it before detach()ing the thread handle (Session is shared-
+	// ptr-owned by the worker, so dtor only runs after the last ref
+	// drops — and that ref is held by the worker lambda, which only
+	// releases it as a final statement).
+	std::atomic<bool>               m_worker_exited{false};
+	std::mutex                      m_socket_mu;
+	std::thread                     m_stream_worker;
+	// Whether this session is accounted against
+	// g_streaming_session_count. Set in DispatchStreaming after a
+	// successful slot acquisition; the dtor decrements iff this is
+	// true so refused-cap sessions don't double-account.
+	bool                            m_session_slot_held = false;
+};
+
+
+// Accept loop. One Listener per HttpServer; spawns a Session per
+// connection via shared_from_this.
+class Listener : public std::enable_shared_from_this<Listener> {
+public:
+	Listener(asio::io_context &ioc, tcp::endpoint endpoint,
+	         CHttpServer::Handler handler,
+	         CHttpServer::StreamingResolver streaming_resolver,
+	         CHttpServer::StreamingHandler  streaming_handler,
+	         CHttpServer::StreamingPreflight streaming_preflight)
+		: m_ioc(ioc),
+		  m_acceptor(asio::make_strand(ioc)),
+		  m_handler(std::move(handler)),
+		  m_streaming_resolver(std::move(streaming_resolver)),
+		  m_streaming_handler(std::move(streaming_handler)),
+		  m_streaming_preflight(std::move(streaming_preflight))
+	{
+		beast::error_code ec;
+		m_acceptor.open(endpoint.protocol(), ec);
+		if (ec) { m_error = ec.message(); return; }
+		m_acceptor.set_option(asio::socket_base::reuse_address(true), ec);
+		if (ec) { m_error = ec.message(); return; }
+		m_acceptor.bind(endpoint, ec);
+		if (ec) { m_error = ec.message(); return; }
+		m_acceptor.listen(asio::socket_base::max_listen_connections, ec);
+		if (ec) { m_error = ec.message(); return; }
+	}
+
+	bool Ok() const { return m_error.empty(); }
+	const std::string &Error() const { return m_error; }
+
+	void Run() { DoAccept(); }
+	void Stop()
+	{
+		beast::error_code ec;
+		m_acceptor.close(ec);
+		// Cancel every live SSE session's socket so workers blocked
+		// inside synchronous Beast writes return promptly. Without
+		// this, a slow peer holds its worker thread inside the
+		// write call until the kernel TCP timeout (~minutes) and
+		// CHttpServer::Stop joins the io_context thread, which
+		// joins indefinitely waiting for the workers.
+		std::vector<std::shared_ptr<Session>> live;
+		{
+			std::lock_guard<std::mutex> g(g_live_streams_mu);
+			live.reserve(g_live_streams.size());
+			for (auto &w : g_live_streams) {
+				if (auto s = w.lock()) live.push_back(std::move(s));
+			}
+			g_live_streams.clear();
+		}
+		for (auto &s : live) s->RequestCancel();
+	}
+
+private:
+	void DoAccept()
+	{
+		auto self = shared_from_this();
+		m_acceptor.async_accept(asio::make_strand(m_ioc),
+			[self](beast::error_code ec, tcp::socket socket) {
+				if (!ec) {
+					std::make_shared<Session>(
+						std::move(socket),
+						self->m_handler,
+						self->m_streaming_resolver,
+						self->m_streaming_handler,
+						self->m_streaming_preflight)->Start();
+				}
+				// Loop unless the acceptor has been closed. operation_aborted
+				// fires on Stop() and signals "exit cleanly".
+				if (ec != asio::error::operation_aborted) {
+					self->DoAccept();
+				}
+			});
+	}
+
+	asio::io_context              &m_ioc;
+	tcp::acceptor                  m_acceptor;
+	CHttpServer::Handler           m_handler;
+	CHttpServer::StreamingResolver m_streaming_resolver;
+	CHttpServer::StreamingHandler  m_streaming_handler;
+	CHttpServer::StreamingPreflight m_streaming_preflight;
+	std::string                    m_error;
+};
+
+}  // namespace
+
+
+struct CHttpServer::Impl {
+	asio::io_context           ioc{1};
+	std::shared_ptr<Listener>  listener;
+	std::thread                thread;
+	std::atomic<bool>          running{false};
+};
+
+
+CHttpServer::CHttpServer()  = default;
+
+CHttpServer::~CHttpServer()
+{
+	Stop();
+}
+
+
+bool CHttpServer::Start(const std::string &bind_address,
+                        unsigned           port,
+                        Handler            handler,
+                        StreamingResolver  streaming_resolver,
+                        StreamingHandler   streaming_handler,
+                        StreamingPreflight streaming_preflight)
+{
+	if (m_impl) {
+		m_lastError = "HttpServer already started";
+		return false;
+	}
+	m_impl = std::make_unique<Impl>();
+
+	beast::error_code ec;
+	const auto addr = asio::ip::make_address(bind_address, ec);
+	if (ec) {
+		m_lastError = "invalid bind address '" + bind_address + "': " + ec.message();
+		m_impl.reset();
+		return false;
+	}
+	tcp::endpoint endpoint(addr, static_cast<unsigned short>(port));
+
+	// Bind hygiene warning. amuleapi's HTTP server uses a thread-
+	// per-streaming-session model bounded by a process-wide cap
+	// (kMaxConcurrentStreamingSessions). On loopback this is fine
+	// — the only callers are the operator's own clients. Off
+	// loopback, the same model is a DoS amplifier: any peer can
+	// open enough preauth connections to consume the cap and lock
+	// out legitimate subscribers. Surface a one-time WARN on
+	// startup so an operator switching the bind catches this in
+	// the daemon log; the SSE session cap still enforces the
+	// upper bound regardless.
+	if (!addr.is_loopback()) {
+		std::cerr << "amuleapi: WARN BindAddress=" << bind_address
+		          << " is not loopback. SSE sessions are capped at "
+		          << kMaxConcurrentStreamingSessions
+		          << " concurrent — beyond that the daemon returns "
+		             "503. Put a reverse proxy in front for remote "
+		             "access.\n";
+	}
+
+	m_impl->listener = std::make_shared<Listener>(
+		m_impl->ioc, endpoint, std::move(handler),
+		std::move(streaming_resolver), std::move(streaming_handler),
+		std::move(streaming_preflight));
+	if (!m_impl->listener->Ok()) {
+		m_lastError = "bind to " + bind_address + ":" + std::to_string(port)
+			+ " failed: " + m_impl->listener->Error();
+		m_impl.reset();
+		return false;
+	}
+	m_impl->listener->Run();
+
+	m_impl->running.store(true, std::memory_order_release);
+	m_impl->thread = std::thread([this]{
+		try {
+			m_impl->ioc.run();
+		} catch (const std::exception &e) {
+			// io_context exception propagation: the server thread dies
+			// quietly. Catch + log to stderr so an operator running in
+			// foreground sees a one-line cause; daemon mode loses the
+			// message.
+			std::cerr << "amuleapi: HTTP I/O loop exited on exception: "
+			          << e.what() << std::endl;
+		}
+		m_impl->running.store(false, std::memory_order_release);
+	});
+	return true;
+}
+
+
+void CHttpServer::Stop()
+{
+	if (!m_impl) return;
+	if (m_impl->listener) m_impl->listener->Stop();
+	m_impl->ioc.stop();
+	if (m_impl->thread.joinable()) m_impl->thread.join();
+	m_impl.reset();
+}
diff --git a/src/webapi/HttpServer.h b/src/webapi/HttpServer.h
new file mode 100644
index 0000000000..79a82b6086
--- /dev/null
+++ b/src/webapi/HttpServer.h
@@ -0,0 +1,152 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#ifndef WEBAPI_HTTPSERVER_H
+#define WEBAPI_HTTPSERVER_H
+
+#include <functional>
+#include <map>
+#include <memory>
+#include <string>
+#include <thread>
+
+#include <boost/optional.hpp>
+
+
+// Boost.Beast-based HTTP/1.1 server. Runs in its own std::thread —
+// boost::asio::io_context::run() is blocking and Beast's async
+// chain stays inside that thread until Stop() is called.
+//
+// Deliberately doesn't share state with the wxApp thread. Handlers
+// that need EC use the wxQueueEvent-based bridge in Api.cpp to fan
+// out onto the wxApp thread; HttpServer stays transport-only.
+
+namespace boost { namespace asio { class io_context; } }
+
+class CHttpServer {
+public:
+	// The dispatch callback runs on the HTTP server's I/O thread.
+	// Anything stateful it touches must be either thread-safe or
+	// trampolined onto the wxApp thread.
+	struct Request {
+		std::string method;            // "GET", "POST", ...
+		std::string target;            // raw URI: "/api/v0/version?x=1"
+		std::map<std::string, std::string> headers;
+		std::string body;
+		// Client IP as observed by the accept socket. amuleapi rate-
+		// limits by this string verbatim; the `X-Forwarded-For` honor
+		// toggle is a deferred follow-up (		// implementation notes).
+		std::string remote_addr;
+	};
+
+	struct Response {
+		unsigned    status = 200;
+		std::string content_type = "application/json";
+		std::map<std::string, std::string> headers;
+		std::string body;
+	};
+
+	using Handler = std::function<Response(const Request &)>;
+
+	// long-lived streaming responses (SSE). The streaming
+	// handler is given a `Writer` it can use to push chunks at will;
+	// the connection stays open until the writer signals close or
+	// the peer disconnects.
+	class Writer {
+	public:
+		// Write a chunk of bytes to the connection. Returns false if
+		// the connection has been torn down (peer disconnect or
+		// shutdown) — caller should stop pushing and let the session
+		// die. Thread-safe: implementations post the write to the
+		// io_context strand, so a caller on any thread is safe.
+		virtual bool Write(const std::string &chunk) = 0;
+		// True if the peer is still connected. Cheap to poll; useful
+		// for the per-stream heartbeat timer to bail when the client
+		// has hung up between pushes.
+		virtual bool Alive() const = 0;
+		virtual ~Writer() = default;
+	};
+
+	// StreamingHandler returns the response head (status, content_type,
+	// initial headers) AND keeps writing chunks via the Writer until it
+	// returns. The session's lifetime extends as long as the handler
+	// hasn't returned AND the connection is alive — typical impls run
+	// an event loop inside the handler and exit when the connection
+	// closes (which Writer::Alive surfaces).
+	using StreamingHandler = std::function<void(
+		const Request &, Writer &writer,
+		unsigned &http_status, std::string &content_type,
+		std::map<std::string, std::string> &response_headers)>;
+
+	// Optional resolver: tells the HTTP server whether an incoming
+	// request should be dispatched to the streaming handler (true) or
+	// the normal Handler (false). The current wiring matches "GET
+	// /api/v0/events"; other endpoints stay request/response.
+	using StreamingResolver = std::function<bool(const Request &)>;
+
+	// Optional preflight: runs synchronously on the I/O thread BEFORE
+	// the per-session worker thread is spawned and BEFORE the 32-slot
+	// concurrency budget is claimed. Returns boost::none to admit the
+	// connection; returns a populated Response to reject it (the
+	// response is written verbatim and the connection closes). Used
+	// to push the SSE auth check off the worker thread so an
+	// unauthenticated peer can't tie up a slot for the read-timeout
+	// window. Empty preflight (default) preserves the pre-existing
+	// "auth inside the handler" behaviour.
+	using StreamingPreflight = std::function<
+		boost::optional<Response>(const Request &)>;
+
+	// Bind + listen on `bind_address`:`port`. Returns false (and
+	// populates LastError) on bind failure — the most common reason
+	// is the port being in use by another amuleapi instance or a
+	// stale TIME_WAIT socket.
+	bool Start(const std::string &bind_address,
+	           unsigned           port,
+	           Handler            handler,
+	           StreamingResolver  streaming_resolver = nullptr,
+	           StreamingHandler   streaming_handler  = nullptr,
+	           StreamingPreflight streaming_preflight = nullptr);
+
+	// Stops the io_context, joins the thread. Safe to call from any
+	// thread; Start() must have succeeded.
+	void Stop();
+
+	const std::string &LastError() const { return m_lastError; }
+
+	// PIMPL — `Impl` holds the boost::asio io_context + the std::thread.
+	// Constructor / destructor are declared but defined out-of-line in
+	// HttpServer.cpp so callers don't need Boost.Asio's headers on the
+	// include path and `std::is_destructible<CHttpServer>` doesn't probe
+	// the incomplete `Impl` from foreign translation units.
+	CHttpServer();
+	~CHttpServer();
+
+private:
+	struct Impl;
+	std::unique_ptr<Impl> m_impl;
+	std::string           m_lastError;
+};
+
+
+#endif // WEBAPI_HTTPSERVER_H
diff --git a/src/webapi/Refresher.cpp b/src/webapi/Refresher.cpp
new file mode 100644
index 0000000000..7cf1a00195
--- /dev/null
+++ b/src/webapi/Refresher.cpp
@@ -0,0 +1,1476 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+// Pure EC-tag-to-State translation layer. No CamuleapiApp dependency
+// — the per-tick orchestration (`RefresherTick` + `TwoPhaseRefresh`)
+// lives in RefresherTick.cpp so the unit tests can link these
+// transformations in isolation.
+
+#include "Refresher.h"
+
+#include "State.h"
+
+#include "Constants.h"          // PS_* / PR_* / US_* / DS_* / OBST_* enums
+#include "ClientList.h"         // buddyState enum (Disconnected/Connecting/Connected)
+#include "ClientCredits.h"      // EIdentState (IS_NOTAVAILABLE / IS_IDENTIFIED / ...)
+#include "Server.h"             // SRV_PR_* server priority constants
+#include "RLE.h"                // PartFileEncoderData (stateful gap/part decoder)
+#include "Types.h"              // ArrayOfUInts16 / ArrayOfUInts64
+#include "include/protocol/ed2k/ClientSoftware.h"   // SO_* client-software enum
+
+#include <ec/cpp/ECSpecialTags.h>
+#include <ec/cpp/ECPacket.h>
+
+#include <algorithm>
+#include <cctype>
+#include <cstdio>
+#include <cstring>
+#include <set>
+#include <string>
+
+
+namespace webapi {
+
+
+namespace {
+
+const char *Ed2kStateString(const CEC_ConnState_Tag *conn)
+{
+	if (!conn) return "disconnected";
+	if (conn->IsConnectedED2K()) return "connected";
+	if (conn->IsConnectingED2K()) return "connecting";
+	return "disconnected";
+}
+
+
+const char *KadStateString(const CEC_ConnState_Tag *conn)
+{
+	// Kad has a "running but disconnected" mode (peer-discovery active,
+	// no contact-routing yet); we collapse that into "connecting" so
+	// the API surface uses three states uniformly for both networks.
+	if (!conn || !conn->IsKadRunning()) return "disabled";
+	if (conn->IsConnectedKademlia()) return "connected";
+	return "connecting";
+}
+
+}  // namespace
+
+
+void ParseStatusFromPacket(const CECPacket *resp, StatusSnapshot &out)
+{
+	if (!resp) return;
+
+	const CEC_ConnState_Tag *conn = static_cast<const CEC_ConnState_Tag *>(
+		resp->GetTagByName(EC_TAG_CONNSTATE));
+
+	out.ed2k_state = Ed2kStateString(conn);
+	out.kad_state  = KadStateString(conn);
+
+	if (conn) {
+		out.ed2k_lowid     = conn->HasLowID();
+		out.kad_firewalled = conn->IsKadFirewalled();
+		if (conn->IsConnectedED2K()) {
+			const CECTag *server = conn->GetTagByName(EC_TAG_SERVER);
+			if (server) {
+				const CECTag *name = server->GetTagByName(EC_TAG_SERVER_NAME);
+				if (name) {
+					out.server_name = std::string(name->GetStringData().utf8_str());
+				}
+					out.server_ip   = std::string(server->GetIPv4Data().StringIP().utf8_str());
+				out.server_port = server->GetIPv4Data().m_port;
+			}
+		}
+	}
+
+	if (const CECTag *t = resp->GetTagByName(EC_TAG_STATS_DL_SPEED)) {
+		out.download_bps = static_cast<std::uint64_t>(t->GetInt());
+	}
+	if (const CECTag *t = resp->GetTagByName(EC_TAG_STATS_UL_SPEED)) {
+		out.upload_bps = static_cast<std::uint64_t>(t->GetInt());
+	}
+	if (const CECTag *t = resp->GetTagByName(EC_TAG_STATS_UL_QUEUE_LEN)) {
+		out.ul_queue_len = static_cast<std::uint32_t>(t->GetInt());
+	}
+	if (const CECTag *t = resp->GetTagByName(EC_TAG_STATS_TOTAL_SRC_COUNT)) {
+		out.total_src_count = static_cast<std::uint32_t>(t->GetInt());
+	}
+	// Nickname intentionally absent: it isn't shipped in the
+	// EC_OP_STAT_REQ response. amuled returns it from
+	// EC_OP_GET_PREFERENCES / EC_OP_GET_STATSTREE@DETAIL_WEB; the
+	// /preferences endpoint exposes it instead.
+}
+
+
+namespace {
+
+// PartFile status code (PS_*, see Constants.h) → wire string. amule
+// has more codes than the API surface — we collapse "completing"/
+// "complete"/"hashing" etc. to the names a curl-tests reader would
+// recognise. "downloading" is overloaded: it covers PS_READY (the
+// daemon's "transferring" state) AND PS_EMPTY (no sources right now
+// but the file isn't paused) — clients distinguish by reading
+// `speed_bps` and `sources.transferring`.
+const char *DownloadStatusName(std::uint8_t ps_code, bool stopped)
+{
+	// PS_COMPLETE / PS_COMPLETING take priority over `stopped` —
+	// amuled holds finished downloads in `m_completedDownloads` with
+	// the EC_TAG_PARTFILE_STOPPED flag set, so a naive `if (stopped)
+	// return "paused"` early-out masks every cleared-pending file
+	// as still-paused. The "completed" wire string is reserved for
+	// the precise semantic "in m_completedDownloads, awaiting clear"
+	// — consumers (and the /downloads default filter) rely on it.
+	if (ps_code == PS_COMPLETE)   return "completed";
+	if (ps_code == PS_COMPLETING) return "completing";
+
+	if (stopped)            return "paused";   // PS_PAUSED is implied
+	                                           // by EC_TAG_PARTFILE_STOPPED
+	switch (ps_code) {
+		case PS_READY:            return "downloading";
+		case PS_EMPTY:            return "downloading";
+		case PS_WAITING_FOR_HASH: return "waiting";
+		case PS_HASHING:          return "hashing";
+		case PS_ERROR:            return "erroneous";
+		case PS_INSUFFICIENT:     return "insufficient_disk";
+		case PS_PAUSED:           return "paused";
+		case PS_ALLOCATING:       return "allocating";
+		default:                  return "unknown";
+	}
+}
+
+
+// The auto-priority flag is encoded as `prio + 10`, NOT bit-7
+// (`& 0x80`). Pattern lifted from amule-remote-gui.cpp:1424:
+//
+// if (m_iUpPriorityEC >= 10) {
+//      m_iUpPriority    = m_iUpPriorityEC - 10;
+//      m_bAutoUpPriority = true;
+//  }
+//
+// Same encoding for `EC_TAG_KNOWNFILE_PRIO` (shared, up-side) and
+// `EC_TAG_PARTFILE_PRIO` (downloads, down-side). Using bit-7 here
+// silently mis-labels every auto-priority entry as "normal" because
+// the PR_* enum values are tiny and never overlap with the 0x80 bit.
+constexpr std::uint8_t kAutoPriorityOffset = 10;
+
+const char *DownloadPriorityName(std::uint8_t pr_code_raw, bool &auto_out)
+{
+	std::uint8_t pr;
+	if (pr_code_raw >= kAutoPriorityOffset) {
+		pr        = pr_code_raw - kAutoPriorityOffset;
+		auto_out  = true;
+	} else {
+		pr        = pr_code_raw;
+		auto_out  = false;
+	}
+	switch (pr) {
+		case PR_VERY_LOW:  return "very_low";
+		case PR_LOW:       return "low";
+		case PR_NORMAL:    return "normal";
+		case PR_HIGH:      return "high";
+		case PR_VERYHIGH:  return "release";
+		case PR_AUTO:      auto_out = true; return "auto";
+		default:           return "normal";
+	}
+}
+
+
+// Shared-file up-priority. Same `+ 10` auto-flag encoding (see
+// ECSpecialCoreTags.cpp:236 — `(IsAutoUpPriority() ? GetUpPriority()
+// + 10 : GetUpPriority())`). Auto is surfaced as the literal "auto"
+// string because /shared doesn't expose a separate priority_auto
+// field (it's an upload-side cosmetic choice, not a queue-priority
+// driver like for downloads).
+const char *SharedPriorityName(std::uint8_t pr_code)
+{
+	const std::uint8_t pr = pr_code >= kAutoPriorityOffset
+		? pr_code - kAutoPriorityOffset
+		: pr_code;
+	const bool is_auto = pr_code >= kAutoPriorityOffset;
+	switch (pr) {
+		case PR_VERY_LOW: return is_auto ? "very_low_auto" : "very_low";
+		case PR_LOW:      return is_auto ? "low_auto"      : "low";
+		case PR_NORMAL:   return is_auto ? "normal_auto"   : "normal";
+		case PR_HIGH:     return is_auto ? "high_auto"     : "high";
+		case PR_VERYHIGH: return is_auto ? "release_auto"  : "release";
+		case PR_AUTO:     return "auto";
+		default:          return "normal";
+	}
+}
+
+}  // namespace
+
+
+namespace {
+
+// Lowercase 32-char hex MD4 from a tag.
+std::string TagHashLower(const CEC_SharedFile_Tag *sf)
+{
+	std::string h(sf->FileHashString().utf8_str());
+	std::transform(h.begin(), h.end(), h.begin(),
+		[](unsigned char c) { return std::tolower(c); });
+	return h;
+}
+
+
+// Merge a CEC_PartFile_Tag's PRESENT child tags into an existing
+// FileSnapshot. Absent tags leave the corresponding field unchanged
+// — that's the point of INC mode.
+//
+// Identity (name, ed2k_link, size, priority) lives at the top level
+// because both walkers populate it; download-specific stats land in
+// `f.download`. The caller is responsible for setting f.ecid + f.hash
+// on first encounter and for flipping f.is_downloading=true.
+//
+// `is_new` distinguishes first-encounter from INC update — used only
+// for the status-string re-derive (idle-on-status-suppressed shouldn't
+// silently lose the prior status).
+void MergePartFileTag(const CEC_PartFile_Tag *pf, FileSnapshot &f,
+                      bool is_new)
+{
+	wxString fn;
+	if (pf->FileName(fn)) {
+		f.name = std::string(fn.utf8_str());
+	}
+	{
+		const wxString link = pf->FileEd2kLink();
+		if (!link.IsEmpty()) {
+			f.ed2k_link = std::string(link.utf8_str());
+		}
+	}
+	{
+		std::uint64_t v = f.size;
+		if (pf->AssignIfExist(EC_TAG_PARTFILE_SIZE_FULL, v)) f.size = v;
+	}
+	{
+		std::uint64_t v = f.download.size_done;
+		if (pf->AssignIfExist(EC_TAG_PARTFILE_SIZE_DONE, v)) f.download.size_done = v;
+	}
+	{
+		std::uint64_t v = f.download.size_xfer;
+		if (pf->AssignIfExist(EC_TAG_PARTFILE_SIZE_XFER, v)) f.download.size_xfer = v;
+	}
+	{
+		std::uint32_t v = f.download.speed_bps;
+		if (pf->AssignIfExist(EC_TAG_PARTFILE_SPEED, v)) f.download.speed_bps = v;
+	}
+	{
+		// Status + stopped flag interact — re-derive the wire string
+		// whenever either changed.
+		std::uint8_t fs = 0;
+		bool         stopped = false;
+		const bool fs_present   = pf->AssignIfExist(EC_TAG_PARTFILE_STATUS,  fs);
+		const bool stop_present = pf->AssignIfExist(EC_TAG_PARTFILE_STOPPED, stopped);
+		if (fs_present || stop_present || is_new) {
+			f.download.status = DownloadStatusName(
+				fs_present ? fs : pf->FileStatus(),
+				stop_present ? stopped : pf->Stopped());
+		}
+	}
+	{
+		std::uint8_t pr_raw = 0;
+		if (pf->AssignIfExist(EC_TAG_PARTFILE_PRIO, pr_raw)) {
+			bool prio_auto = false;
+			f.priority               = DownloadPriorityName(pr_raw, prio_auto);
+			f.download.priority_auto = prio_auto;
+		}
+	}
+	{
+		std::uint8_t cat = 0;
+		if (pf->AssignIfExist(EC_TAG_PARTFILE_CAT, cat)) f.download.category = cat;
+	}
+	{
+		std::uint16_t v = 0;
+		if (pf->AssignIfExist(EC_TAG_PARTFILE_SOURCE_COUNT, v))
+			f.download.sources_total = v;
+		if (pf->AssignIfExist(EC_TAG_PARTFILE_SOURCE_COUNT_NOT_CURRENT, v))
+			f.download.sources_not_current = v;
+		if (pf->AssignIfExist(EC_TAG_PARTFILE_SOURCE_COUNT_XFER, v))
+			f.download.sources_transferring = v;
+		if (pf->AssignIfExist(EC_TAG_PARTFILE_SOURCE_COUNT_A4AF, v))
+			f.download.sources_a4af = v;
+	}
+	// Recompute percent unconditionally — both inputs may have moved.
+	f.download.percent = (f.size > 0)
+		? (static_cast<double>(f.download.size_done) * 100.0
+		   / static_cast<double>(f.size))
+		: 0.0;
+}
+
+
+// State-code → wire-string decoders for the four enums amule ships
+// on `EC_TAG_CLIENT_*_STATE`. Wire forms match the names amule uses
+// in its UI (Constants.h enums, lowercased). All decoders fall back
+// to "unknown" for codes outside the enum.
+
+const char *ClientUploadStateName(std::uint8_t code)
+{
+	switch (code) {
+		case US_UPLOADING:      return "uploading";
+		case US_ONUPLOADQUEUE:  return "queued";
+		case US_WAITCALLBACK:   return "waitcallback";
+		case US_CONNECTING:     return "connecting";
+		case US_PENDING:        return "pending";
+		case US_LOWTOLOWIP:     return "lowtolowip";
+		case US_BANNED:         return "banned";
+		case US_ERROR:          return "error";
+		case US_NONE:           return "idle";
+		default:                return "unknown";
+	}
+}
+
+
+const char *ClientDownloadStateName(std::uint8_t code)
+{
+	switch (code) {
+		case DS_DOWNLOADING:        return "downloading";
+		case DS_ONQUEUE:            return "onqueue";
+		case DS_CONNECTED:          return "connected";
+		case DS_CONNECTING:         return "connecting";
+		case DS_WAITCALLBACK:       return "waitcallback";
+		case DS_WAITCALLBACKKAD:    return "waitcallbackkad";
+		case DS_REQHASHSET:         return "reqhashset";
+		case DS_NONEEDEDPARTS:      return "noneededparts";
+		case DS_TOOMANYCONNS:       return "toomanyconns";
+		case DS_TOOMANYCONNSKAD:    return "toomanyconnskad";
+		case DS_LOWTOLOWIP:         return "lowtolowip";
+		case DS_BANNED:             return "banned";
+		case DS_ERROR:              return "error";
+		case DS_NONE:               return "idle";
+		case DS_REMOTEQUEUEFULL:    return "remotequeuefull";
+		default:                    return "unknown";
+	}
+}
+
+
+const char *ClientIdentStateName(std::uint8_t code)
+{
+	switch (code) {
+		case IS_NOTAVAILABLE:   return "not_available";
+		case IS_IDNEEDED:       return "id_needed";
+		case IS_IDENTIFIED:     return "identified";
+		case IS_IDFAILED:       return "id_failed";
+		case IS_IDBADGUY:       return "bad_guy";
+		default:                return "unknown";
+	}
+}
+
+
+const char *ClientSoftwareName(std::uint32_t code)
+{
+	// Subset that covers the bulk of the live ed2k population —
+	// every client we'd ever realistically meet on the wire. SO_UNKNOWN
+	// and SO_COMPAT_UNK collapse to "unknown" / "compat" so consumers
+	// see a stable label even when amuled couldn't fingerprint the
+	// peer's software.
+	switch (code) {
+		case SO_EMULE:          return "emule";
+		case SO_CDONKEY:        return "cdonkey";
+		case SO_LXMULE:         return "lxmule";
+		case SO_AMULE:          return "amule";
+		case SO_SHAREAZA:
+		case SO_NEW2_SHAREAZA:
+		case SO_NEW_SHAREAZA:   return "shareaza";
+		case SO_EMULEPLUS:      return "emule_plus";
+		case SO_HYDRANODE:      return "hydranode";
+		case SO_NEW2_MLDONKEY:
+		case SO_MLDONKEY:
+		case SO_NEW_MLDONKEY:   return "mldonkey";
+		case SO_LPHANT:         return "lphant";
+		case SO_EDONKEYHYBRID:  return "edonkey_hybrid";
+		case SO_EDONKEY:        return "edonkey";
+		case SO_OLDEMULE:       return "old_emule";
+		case SO_UNKNOWN:        return "unknown";
+		case SO_COMPAT_UNK:     return "compat";
+		default:                return "unknown";
+	}
+}
+
+
+const char *ClientObfuscationName(std::uint8_t code)
+{
+	switch (code) {
+		case OBST_UNDEFINED:      return "undefined";
+		case OBST_ENABLED:        return "enabled";
+		case OBST_SUPPORTED:      return "supported";
+		case OBST_NOT_SUPPORTED:  return "not_supported";
+		case OBST_DISABLED:       return "disabled";
+		default:                  return "unknown";
+	}
+}
+
+
+// Format an IP from EC_TAG_CLIENT_USER_IP. The EC tag holds a
+// 32-bit host-order IPv4; we render it dotted-quad. Returns "" for
+// zero IPs (commonly the case for clients we've never confirmed).
+std::string FormatClientIpv4(std::uint32_t ip_he)
+{
+	if (ip_he == 0) return std::string();
+	char buf[16];
+	std::snprintf(buf, sizeof(buf), "%u.%u.%u.%u",
+		static_cast<unsigned>((ip_he      ) & 0xFFu),
+		static_cast<unsigned>((ip_he >>  8) & 0xFFu),
+		static_cast<unsigned>((ip_he >> 16) & 0xFFu),
+		static_cast<unsigned>((ip_he >> 24) & 0xFFu));
+	return std::string(buf);
+}
+
+
+// Merge a `CEC_UpDownClient_Tag` into an existing ClientSnapshot.
+// On a cache-miss the caller pre-populates ecid + hashes; on a hit
+// the AssignIfExist pattern leaves cached values intact when the
+// tag is CValueMap-suppressed by amuled.
+void MergeClientTag(const CEC_UpDownClient_Tag *c, ClientSnapshot &cs,
+                    bool is_new,
+                    const std::map<std::uint32_t, std::string> &file_hash_by_ecid)
+{
+	if (const CECTag *t = c->GetTagByName(EC_TAG_CLIENT_NAME)) {
+		cs.client_name = std::string(t->GetStringData().utf8_str());
+	}
+	if (const CECTag *t = c->GetTagByName(EC_TAG_CLIENT_HASH)) {
+		cs.user_hash = std::string(t->GetMD4Data().Encode().Lower().utf8_str());
+	}
+	{
+		std::uint32_t v = 0;
+		if (c->AssignIfExist(EC_TAG_CLIENT_USER_IP, v)) cs.ip = FormatClientIpv4(v);
+	}
+	{
+		std::uint16_t v = 0;
+		if (c->AssignIfExist(EC_TAG_CLIENT_USER_PORT, v)) cs.port = v;
+	}
+	{
+		std::uint32_t v = 0;
+		if (c->AssignIfExist(EC_TAG_CLIENT_SOFTWARE, v)) cs.software = ClientSoftwareName(v);
+	}
+	if (const CECTag *t = c->GetTagByName(EC_TAG_CLIENT_SOFT_VER_STR)) {
+		cs.software_version = std::string(t->GetStringData().utf8_str());
+	}
+	if (const CECTag *t = c->GetTagByName(EC_TAG_CLIENT_OS_INFO)) {
+		cs.os_info = std::string(t->GetStringData().utf8_str());
+	}
+	{
+		std::uint8_t v = 0;
+		if (c->AssignIfExist(EC_TAG_CLIENT_UPLOAD_STATE, v)) {
+			cs.upload_state = ClientUploadStateName(v);
+		} else if (is_new) {
+			cs.upload_state = "unknown";
+		}
+	}
+	{
+		std::uint8_t v = 0;
+		if (c->AssignIfExist(EC_TAG_CLIENT_DOWNLOAD_STATE, v)) {
+			cs.download_state = ClientDownloadStateName(v);
+		} else if (is_new) {
+			cs.download_state = "unknown";
+		}
+	}
+	{
+		std::uint8_t v = 0;
+		if (c->AssignIfExist(EC_TAG_CLIENT_IDENT_STATE, v)) {
+			cs.ident_state = ClientIdentStateName(v);
+		} else if (is_new) {
+			cs.ident_state = "unknown";
+		}
+	}
+	// REMOTE_FILENAME = the file we are downloading from this peer
+	// (`m_clientFilename` is set from OP_REQFILENAMEANSWER; see
+	// DownloadClient.cpp:350). Live only at INC_UPDATE detail.
+	wxString fn;
+	if (c->RemoteFilename(fn)) {
+		cs.download_file_name = std::string(fn.utf8_str());
+	}
+	// UPLOAD_FILE / REQUEST_FILE carry amuled-side ECIDs (the unified
+	// m_FileEncoder map's IDs). Resolve to MD4 hashes via the
+	// file_hash_by_ecid snapshot the caller built from m_files this
+	// tick. Empty hash if the ECID isn't in the map — file may have
+	// been removed between the file walkers and this client walker.
+	{
+		std::uint32_t v = 0;
+		if (c->AssignIfExist(EC_TAG_CLIENT_UPLOAD_FILE, v) && v != 0) {
+			const auto it = file_hash_by_ecid.find(v);
+			cs.upload_file_hash = (it != file_hash_by_ecid.end())
+				? it->second : std::string();
+		}
+	}
+	{
+		std::uint32_t v = 0;
+		if (c->AssignIfExist(EC_TAG_CLIENT_REQUEST_FILE, v) && v != 0) {
+			const auto it = file_hash_by_ecid.find(v);
+			cs.download_file_hash = (it != file_hash_by_ecid.end())
+				? it->second : std::string();
+		}
+	}
+	{
+		std::uint64_t v = cs.xfer_up_session;
+		if (c->AssignIfExist(EC_TAG_CLIENT_UPLOAD_SESSION, v)) cs.xfer_up_session = v;
+	}
+	{
+		std::uint64_t v = cs.xfer_down_session;
+		if (c->AssignIfExist(EC_TAG_PARTFILE_SIZE_XFER, v)) cs.xfer_down_session = v;
+	}
+	{
+		std::uint64_t v = cs.xfer_up_total;
+		if (c->AssignIfExist(EC_TAG_CLIENT_UPLOAD_TOTAL, v)) cs.xfer_up_total = v;
+	}
+	{
+		std::uint64_t v = cs.xfer_down_total;
+		if (c->AssignIfExist(EC_TAG_CLIENT_DOWNLOAD_TOTAL, v)) cs.xfer_down_total = v;
+	}
+	{
+		std::uint32_t v = cs.upload_speed_bps;
+		if (c->AssignIfExist(EC_TAG_CLIENT_UP_SPEED, v)) cs.upload_speed_bps = v;
+	}
+	{
+		// EC_TAG_CLIENT_DOWN_SPEED is emitted as a double-encoded
+		// CECTag (see ECSpecialCoreTags.cpp:289-291 — KBps as a
+		// double). AssignIfExist with a uint won't pick it up cleanly;
+		// extract via the typed read and convert.
+		if (const CECTag *t = c->GetTagByName(EC_TAG_CLIENT_DOWN_SPEED)) {
+			const double kBps = t->GetDoubleData();
+			cs.download_speed_bps =
+				static_cast<std::uint32_t>(kBps * 1024.0);
+		}
+	}
+	{
+		std::uint32_t v = cs.queue_waiting_position;
+		if (c->AssignIfExist(EC_TAG_CLIENT_WAITING_POSITION, v)) cs.queue_waiting_position = v;
+	}
+	{
+		std::uint16_t v = cs.remote_queue_rank;
+		if (c->AssignIfExist(EC_TAG_CLIENT_REMOTE_QUEUE_RANK, v)) cs.remote_queue_rank = v;
+	}
+	{
+		std::uint32_t v = cs.score;
+		if (c->AssignIfExist(EC_TAG_CLIENT_SCORE, v)) cs.score = v;
+	}
+	{
+		std::uint8_t v = 0;
+		if (c->AssignIfExist(EC_TAG_CLIENT_OBFUSCATION_STATUS, v)) {
+			cs.obfuscation_status = ClientObfuscationName(v);
+		}
+	}
+	{
+		bool v = false;
+		if (c->AssignIfExist(EC_TAG_CLIENT_FRIEND_SLOT, v)) cs.friend_slot = v;
+	}
+}
+
+
+void MergeSharedTag(const CEC_SharedFile_Tag *sf, FileSnapshot &f)
+{
+	wxString fn;
+	if (sf->FileName(fn)) {
+		f.name = std::string(fn.utf8_str());
+	}
+	{
+		const wxString link = sf->FileEd2kLink();
+		if (!link.IsEmpty()) {
+			f.ed2k_link = std::string(link.utf8_str());
+		}
+	}
+	{
+		std::uint64_t v = f.size;
+		if (sf->AssignIfExist(EC_TAG_PARTFILE_SIZE_FULL, v)) f.size = v;
+	}
+	{
+		std::uint64_t v = f.shared.xfer_session;
+		if (sf->AssignIfExist(EC_TAG_KNOWNFILE_XFERRED, v)) f.shared.xfer_session = v;
+	}
+	{
+		std::uint64_t v = f.shared.xfer_total;
+		if (sf->AssignIfExist(EC_TAG_KNOWNFILE_XFERRED_ALL, v)) f.shared.xfer_total = v;
+	}
+	{
+		std::uint32_t v = f.shared.requests_session;
+		if (sf->AssignIfExist(EC_TAG_KNOWNFILE_REQ_COUNT, v)) f.shared.requests_session = v;
+	}
+	{
+		std::uint32_t v = f.shared.requests_total;
+		if (sf->AssignIfExist(EC_TAG_KNOWNFILE_REQ_COUNT_ALL, v)) f.shared.requests_total = v;
+	}
+	{
+		std::uint32_t v = f.shared.accepts_session;
+		if (sf->AssignIfExist(EC_TAG_KNOWNFILE_ACCEPT_COUNT, v)) f.shared.accepts_session = v;
+	}
+	{
+		std::uint32_t v = f.shared.accepts_total;
+		if (sf->AssignIfExist(EC_TAG_KNOWNFILE_ACCEPT_COUNT_ALL, v)) f.shared.accepts_total = v;
+	}
+	{
+		std::uint16_t v = 0;
+		if (sf->AssignIfExist(EC_TAG_KNOWNFILE_COMPLETE_SOURCES, v))
+			f.shared.complete_sources = v;
+	}
+	{
+		std::uint8_t pr = 0;
+		if (sf->AssignIfExist(EC_TAG_KNOWNFILE_PRIO, pr)) {
+			f.priority = SharedPriorityName(pr);
+		}
+	}
+}
+
+}  // namespace
+
+
+// --- Downloads (EC_TAG_PARTFILE)
+
+namespace {
+
+// Apply the stateful RLE decode for the gap + part-status blobs on
+// one partfile tag. Allocates `rle_state[ecid]` if absent; mutates
+// it on each call (XOR-deltas against the prior decoded buffer).
+// Output lands in `f.download.decoded_gaps` + `f.download
+// .decoded_part_sources`. HTTP handlers read those without touching
+// the decoder state.
+void DecodeRleBlobsForPartFile(
+	const CEC_PartFile_Tag *pf,
+	FileSnapshot &f,
+	std::map<std::uint32_t, PartFileEncoderData> &rle_state)
+{
+	const std::uint32_t ecid = pf->ID();
+	PartFileEncoderData &enc = rle_state[ecid];
+
+	if (const CECTag *gap_tag = pf->GetTagByName(EC_TAG_PARTFILE_GAP_STATUS)) {
+		ArrayOfUInts64 gaps;
+		enc.DecodeGaps(gap_tag, gaps);
+		f.download.decoded_gaps.assign(gaps.begin(), gaps.end());
+	}
+	if (const CECTag *part_tag = pf->GetTagByName(EC_TAG_PARTFILE_PART_STATUS)) {
+		ArrayOfUInts16 parts;
+		enc.DecodeParts(part_tag, parts);
+		f.download.decoded_part_sources.assign(parts.begin(), parts.end());
+	}
+}
+
+}  // namespace
+
+
+void ApplyGetUpdateToDownloads(
+	const CECPacket *resp,
+	FileMap &cache,
+	std::map<std::uint32_t, PartFileEncoderData> &rle_state)
+{
+	if (!resp) return;
+
+	// Walk the response top level. Three tag-name dispatches:
+	//  * EC_TAG_PARTFILE     → set is_downloading + merge download side
+	//  * EC_TAG_FILE_REMOVED → clear download role; drop entry if it
+	//                          had no shared role either
+	//  * everything else     → handled by sibling Shared/Servers walkers
+	for (CECPacket::const_iterator it = resp->begin(); it != resp->end(); ++it) {
+		const CECTag *t = &*it;
+		const ec_tagname_t name = t->GetTagName();
+
+		if (name == EC_TAG_FILE_REMOVED) {
+			const std::uint32_t ecid = static_cast<std::uint32_t>(t->GetInt());
+			auto fit = cache.find(ecid);
+			if (fit != cache.end()) {
+				fit->second.is_downloading = false;
+				// Reset the download sub-block so a future role-true
+				// transition (or even a stale FindDownload lookup
+				// after the role flag was checked) can't surface
+				// stale stats from this dead downloading period.
+				fit->second.download = FileSnapshot::DownloadSide{};
+				if (!fit->second.is_shared) cache.erase(fit);
+			}
+			rle_state.erase(ecid);
+			continue;
+		}
+		if (name != EC_TAG_PARTFILE) continue;
+
+		const CEC_PartFile_Tag *pf = static_cast<const CEC_PartFile_Tag *>(t);
+		const std::uint32_t ecid = pf->ID();
+
+		auto map_it = cache.find(ecid);
+		if (map_it == cache.end()) {
+			// Brand-new ECID. INC_UPDATE ships HASH/NAME/SIZE on first
+			// encounter (no two-pass needed) so the insert is fully
+			// populated in one pass.
+			FileSnapshot f;
+			f.ecid           = ecid;
+			f.hash           = TagHashLower(pf);
+			f.is_downloading = true;
+			MergePartFileTag(pf, f, /*is_new=*/true);
+			DecodeRleBlobsForPartFile(pf, f, rle_state);
+			cache.emplace(ecid, std::move(f));
+		} else {
+			map_it->second.is_downloading = true;
+			MergePartFileTag(pf, map_it->second, /*is_new=*/false);
+			DecodeRleBlobsForPartFile(pf, map_it->second, rle_state);
+		}
+	}
+}
+
+
+void ApplyGetUpdateToShared(
+	const CECPacket *resp,
+	FileMap &cache)
+{
+	if (!resp) return;
+
+	// amuled's "shared files" surface is the union of completed
+	// knownfiles (`theApp->sharedfiles` → EC_TAG_KNOWNFILE, always
+	// shared) and partfiles with `IsShared()==true` (≥1 chunk complete
+	// → EC_TAG_PARTFILE with `EC_TAG_PARTFILE_SHARED` child tag).
+	// CEC_PartFile_Tag derives from CEC_SharedFile_Tag (same identity
+	// + stat tag names) so we cast and pass through MergeSharedTag.
+	//
+	// EC_TAG_PARTFILE_SHARED is CValueMap-suppressed when unchanged:
+	// present-and-true → set is_shared + merge; present-and-false →
+	// clear is_shared (file stays in m_files if still downloading);
+	// absent → preserve prior is_shared state.
+	//
+	// EC_TAG_FILE_REMOVED markers can target either a partfile or
+	// knownfile ECID (unified server-side); we clear the shared role
+	// + drop the entry if it had no downloading role either.
+	for (CECPacket::const_iterator it = resp->begin(); it != resp->end(); ++it) {
+		const CECTag *t = &*it;
+		const ec_tagname_t name = t->GetTagName();
+
+		if (name == EC_TAG_FILE_REMOVED) {
+			const std::uint32_t ecid = static_cast<std::uint32_t>(t->GetInt());
+			auto fit = cache.find(ecid);
+			if (fit != cache.end()) {
+				fit->second.is_shared = false;
+				fit->second.shared    = FileSnapshot::SharedSide{};
+				if (!fit->second.is_downloading) cache.erase(fit);
+			}
+			continue;
+		}
+		if (name != EC_TAG_KNOWNFILE && name != EC_TAG_PARTFILE) continue;
+
+		const CEC_SharedFile_Tag *sf = static_cast<const CEC_SharedFile_Tag *>(t);
+		const std::uint32_t ecid = sf->ID();
+
+		if (name == EC_TAG_PARTFILE) {
+			const CECTag *shared_flag = sf->GetTagByName(EC_TAG_PARTFILE_SHARED);
+			if (shared_flag) {
+				const bool is_shared = (shared_flag->GetInt() != 0);
+				if (!is_shared) {
+					// Partfile is_shared transitioned false (or
+					// arrived for the first time unshared).
+					// Reset the shared sub-block; entry stays in
+					// m_files because downloading role may still
+					// hold it. If it doesn't, the downloads-walker
+					// FILE_REMOVED will drop it.
+					auto fit = cache.find(ecid);
+					if (fit != cache.end()) {
+						fit->second.is_shared = false;
+						fit->second.shared    = FileSnapshot::SharedSide{};
+					}
+					continue;
+				}
+				// is_shared == true → fall through to the merge below.
+			} else {
+				// Flag suppressed (no change). Only meaningful for an
+				// entry we already know was shared.
+				const auto fit = cache.find(ecid);
+				if (fit == cache.end() || !fit->second.is_shared) continue;
+			}
+		}
+
+		auto map_it = cache.find(ecid);
+		if (map_it == cache.end()) {
+			// Brand-new ECID to the unified map (knownfile arriving
+			// without a prior downloads-walker tick — its first
+			// frame ships HASH unconditionally).
+			FileSnapshot f;
+			f.ecid      = ecid;
+			f.hash      = TagHashLower(sf);
+			f.is_shared = true;
+			MergeSharedTag(sf, f);
+			cache.emplace(ecid, std::move(f));
+		} else {
+			// Existing entry — flip is_shared on, merge fields.
+			// If hash arrived (e.g. KNOWNFILE first frame) and we
+			// don't already have one (rare path: prior partfile-
+			// walker had hash suppressed), capture it now.
+			if (map_it->second.hash.empty()) {
+				const std::string h = TagHashLower(sf);
+				if (!h.empty()) map_it->second.hash = h;
+			}
+			map_it->second.is_shared = true;
+			MergeSharedTag(sf, map_it->second);
+		}
+	}
+}
+
+
+// --- Clients (rides on the EC_TAG_CLIENT container inside the
+// consolidated GET_UPDATE response).
+
+void ApplyGetUpdateToClients(
+	const CECPacket *resp,
+	std::map<std::uint32_t, ClientSnapshot> &cache,
+	const std::map<std::uint32_t, std::string> &file_hash_by_ecid)
+{
+	if (!resp) return;
+	const CECTag *container = resp->GetTagByName(EC_TAG_CLIENT);
+	if (!container) return;
+
+	// Walk the per-client children. Every alive client in
+	// theApp->clientlist surfaces here every tick (the outer
+	// per-client tag is added unconditionally — only the children
+	// are CValueMap-suppressed when unchanged). So we use the
+	// "seen this tick = keep, absent = evict" pattern (same shape
+	// as the servers walker above). There's no FILE_REMOVED
+	// equivalent for clients on the server side.
+	std::set<std::uint32_t> seen;
+	for (CECTag::const_iterator it = container->begin();
+	     it != container->end(); ++it) {
+		const CECTag *t = &*it;
+		if (t->GetTagName() != EC_TAG_CLIENT) continue;
+		const CEC_UpDownClient_Tag *cli =
+			static_cast<const CEC_UpDownClient_Tag *>(t);
+		const std::uint32_t ecid = cli->ID();
+		seen.insert(ecid);
+
+		auto map_it = cache.find(ecid);
+		if (map_it == cache.end()) {
+			ClientSnapshot fresh;
+			fresh.ecid = ecid;
+			MergeClientTag(cli, fresh, /*is_new=*/true,
+			               file_hash_by_ecid);
+			cache.emplace(ecid, std::move(fresh));
+		} else {
+			MergeClientTag(cli, map_it->second, /*is_new=*/false,
+			               file_hash_by_ecid);
+		}
+	}
+
+	// Evict cache entries not seen this tick — they're gone from the
+	// amuled side (peer disconnected, dropped from queue, banned out
+	// of the visible set, etc.).
+	for (auto it = cache.begin(); it != cache.end();) {
+		if (seen.find(it->first) == seen.end()) {
+			it = cache.erase(it);
+		} else {
+			++it;
+		}
+	}
+}
+
+
+// --- /kad (rides on STAT_REQ response) ---------------------------------
+
+namespace {
+
+const char *KadBuddyStatusName(std::uint32_t status_code)
+{
+	// EC ships the `buddyState` enum (ClientList.h) value directly.
+	// Using the enum names rather than literal 0/1/2 so a future
+	// reorder of buddyState can't silently re-label the wire.
+	switch (static_cast<buddyState>(status_code)) {
+		case Disconnected: return "no_buddy";
+		case Connecting:   return "connecting";
+		case Connected:    return "connected";
+		default:           return "unknown";
+	}
+}
+
+// Render a host-byte-order uint32 IP as dotted-quad. amuled emits the
+// Kad address with network bytes already swapped (see
+// `ExternalConn.cpp:761` — `wxUINT32_SWAP_ALWAYS`).
+std::string IPv4ToDotted(std::uint32_t ip_host_order)
+{
+	char buf[24];
+	std::snprintf(buf, sizeof(buf), "%u.%u.%u.%u",
+		(ip_host_order      ) & 0xFF,
+		(ip_host_order >>  8) & 0xFF,
+		(ip_host_order >> 16) & 0xFF,
+		(ip_host_order >> 24) & 0xFF);
+	return std::string(buf);
+}
+
+}  // namespace
+
+
+void ParseKadFromPacket(const CECPacket *resp, KadSnapshot &out)
+{
+	if (!resp) return;
+
+	const CEC_ConnState_Tag *conn = static_cast<const CEC_ConnState_Tag *>(
+		resp->GetTagByName(EC_TAG_CONNSTATE));
+
+	out.state      = KadStateString(conn);
+	if (conn) {
+		out.firewalled = conn->IsKadFirewalled();
+	}
+
+	if (const CECTag *t = resp->GetTagByName(EC_TAG_STATS_KAD_USERS)) {
+		out.users = static_cast<std::uint32_t>(t->GetInt());
+	}
+	if (const CECTag *t = resp->GetTagByName(EC_TAG_STATS_KAD_FILES)) {
+		out.files = static_cast<std::uint32_t>(t->GetInt());
+	}
+	if (const CECTag *t = resp->GetTagByName(EC_TAG_STATS_KAD_NODES)) {
+		out.nodes = static_cast<std::uint32_t>(t->GetInt());
+	}
+
+	// These ship only when Kad is connected (server gates them at
+	// ExternalConn.cpp:755 `if (Kademlia::CKademlia::IsConnected())`).
+	if (const CECTag *t = resp->GetTagByName(EC_TAG_STATS_KAD_FIREWALLED_UDP)) {
+		out.firewalled_udp = (t->GetInt() != 0);
+	}
+	if (const CECTag *t = resp->GetTagByName(EC_TAG_STATS_KAD_INDEXED_SOURCES)) {
+		out.indexed_sources = static_cast<std::uint32_t>(t->GetInt());
+	}
+	if (const CECTag *t = resp->GetTagByName(EC_TAG_STATS_KAD_INDEXED_KEYWORDS)) {
+		out.indexed_keywords = static_cast<std::uint32_t>(t->GetInt());
+	}
+	if (const CECTag *t = resp->GetTagByName(EC_TAG_STATS_KAD_INDEXED_NOTES)) {
+		out.indexed_notes = static_cast<std::uint32_t>(t->GetInt());
+	}
+	if (const CECTag *t = resp->GetTagByName(EC_TAG_STATS_KAD_INDEXED_LOAD)) {
+		out.indexed_load = static_cast<std::uint32_t>(t->GetInt());
+	}
+	if (const CECTag *t = resp->GetTagByName(EC_TAG_STATS_KAD_IP_ADDRESS)) {
+		out.ip = IPv4ToDotted(static_cast<std::uint32_t>(t->GetInt()));
+	}
+	if (const CECTag *t = resp->GetTagByName(EC_TAG_STATS_KAD_IN_LAN_MODE)) {
+		out.in_lan_mode = (t->GetInt() != 0);
+	}
+	if (const CECTag *t = resp->GetTagByName(EC_TAG_STATS_BUDDY_STATUS)) {
+		out.buddy_status = KadBuddyStatusName(
+			static_cast<std::uint32_t>(t->GetInt()));
+	}
+	if (const CECTag *t = resp->GetTagByName(EC_TAG_STATS_BUDDY_IP)) {
+		out.buddy_ip = IPv4ToDotted(static_cast<std::uint32_t>(t->GetInt()));
+	}
+	if (const CECTag *t = resp->GetTagByName(EC_TAG_STATS_BUDDY_PORT)) {
+		out.buddy_port = static_cast<std::uint16_t>(t->GetInt());
+	}
+}
+
+
+// --- /logs/amule (incremental, piggybacks on STAT_REQ) -----------------
+
+void ParseAmuleLogFromPacket(const CECPacket *resp,
+                             std::vector<std::string> &out_new_lines)
+{
+	out_new_lines.clear();
+	if (!resp) return;
+	// `EC_TAG_STATS_LOGGER_MESSAGE` is a parent tag with child
+	// `EC_TAG_STRING` entries, one per new log line drained from
+	// the per-connection CLoggerAccess cursor on the server side
+	// (`ExternalConn.cpp:700-715`). Absent when there's nothing
+	// new since our last tick.
+	const CECTag *logger = resp->GetTagByName(EC_TAG_STATS_LOGGER_MESSAGE);
+	if (!logger) return;
+	for (CECTag::const_iterator it = logger->begin(); it != logger->end(); ++it) {
+		const CECTag *t = &*it;
+		if (t->GetTagName() != EC_TAG_STRING) continue;
+		out_new_lines.emplace_back(t->GetStringData().utf8_str());
+	}
+}
+
+
+// --- /servers (rides on GET_UPDATE response) ---------------------------
+
+namespace {
+
+const char *ServerPriorityName(std::uint32_t prio_code)
+{
+	// SRV_PR_* constants live in `Server.h`. Note the values aren't
+	// monotone with priority (NORMAL=0, HIGH=1, LOW=2) — using the
+	// named macros instead of literal 0/1/2 saves anyone reading
+	// this from re-checking Server.h to remember the order.
+	switch (prio_code) {
+		case SRV_PR_NORMAL: return "normal";
+		case SRV_PR_HIGH:   return "high";
+		case SRV_PR_LOW:    return "low";
+		default:            return "normal";
+	}
+}
+
+
+// Build (or merge into) a ServerSnapshot from one per-server tag.
+// Identity-only tags (name/description/version/IPv4) are subject to
+// CValueMap suppression at the server side, so for an existing entry
+// we leave the cached value alone when the source string is empty.
+void MergeServerTag(const CEC_Server_Tag *st, ServerSnapshot &s, bool is_new)
+{
+	s.ecid = st->ID();
+	{
+		wxString tmp;
+		const std::string n = std::string(st->ServerName(&tmp).utf8_str());
+		if (is_new || !n.empty()) s.name = n;
+	}
+	{
+		wxString tmp;
+		const std::string d = std::string(st->ServerDesc(&tmp).utf8_str());
+		if (is_new || !d.empty()) s.description = d;
+	}
+	{
+		wxString tmp;
+		const std::string v = std::string(st->ServerVersion(&tmp).utf8_str());
+		if (is_new || !v.empty()) s.version = v;
+	}
+	// IP + port shipping shape varies by EC detail level:
+	//  * FULL/WEB/UPDATE (webserver, amulecmd) pack them into the
+	//    OUTER tag as IPv4 data (st->GetIPv4Data()).
+	//  * INC_UPDATE / GET_UPDATE (amulegui, amuleapi) ship them as
+	//    CHILD tags EC_TAG_SERVER_IP + EC_TAG_SERVER_PORT
+	//    (ECSpecialCoreTags.cpp:112-113); the outer tag carries the
+	//    ECID instead, so GetIPv4Data() returns all-zeros and
+	//    /servers[].address silently degrades to "0.0.0.0:0".
+	//
+	// Try the child-tag shape first; fall back to GetIPv4Data() so
+	// any future use of FULL detail still works.
+	{
+		std::uint32_t ip_he = 0;
+		std::uint16_t port  = 0;
+		const bool have_ip   = st->AssignIfExist(EC_TAG_SERVER_IP,   ip_he);
+		const bool have_port = st->AssignIfExist(EC_TAG_SERVER_PORT, port);
+		if (have_ip || have_port) {
+			if (have_ip)   s.ip   = ip_he;
+			if (have_port) s.port = port;
+			// Build "1.2.3.4:port" once we have both halves.
+			if (s.ip != 0 && s.port != 0) {
+				char buf[32];
+				std::snprintf(buf, sizeof(buf), "%u.%u.%u.%u:%u",
+					static_cast<unsigned>((s.ip      ) & 0xFFu),
+					static_cast<unsigned>((s.ip >>  8) & 0xFFu),
+					static_cast<unsigned>((s.ip >> 16) & 0xFFu),
+					static_cast<unsigned>((s.ip >> 24) & 0xFFu),
+					static_cast<unsigned>(s.port));
+				s.address = buf;
+			}
+		}
+		// The FULL-detail fallback that used to read st->GetIPv4Data()
+		// here was removed: amuleapi's refresher only ever asks for
+		// EC_DETAIL_INC_UPDATE (RefresherTick.cpp), so the child-tag
+		// shape above is the only one we observe in production. The
+		// fallback also triggered a libec Debug-build assertion on
+		// non-IPv4 outer tags (RefresherTest fixtures pack the ECID
+		// as a uint32 in the EC_TAG_SERVER slot), aborting the test
+		// process before any assertion in our own code could run.
+		// Resurrect the fallback alongside a public type predicate on
+		// CECTag if a future detail-level shift makes it relevant.
+	}
+	{
+		std::uint32_t v = 0;
+		if (st->AssignIfExist(EC_TAG_SERVER_PING, v)) s.ping_ms = v;
+	}
+	{
+		std::uint32_t v = 0;
+		if (st->AssignIfExist(EC_TAG_SERVER_FAILED, v)) s.failed = v;
+	}
+	{
+		std::uint32_t v = 0;
+		if (st->AssignIfExist(EC_TAG_SERVER_USERS, v)) s.users = v;
+	}
+	{
+		std::uint32_t v = 0;
+		if (st->AssignIfExist(EC_TAG_SERVER_USERS_MAX, v)) s.max_users = v;
+	}
+	{
+		std::uint32_t v = 0;
+		if (st->AssignIfExist(EC_TAG_SERVER_FILES, v)) s.files = v;
+	}
+	{
+		std::uint32_t v = 0;
+		if (st->AssignIfExist(EC_TAG_SERVER_PRIO, v)) {
+			s.priority = ServerPriorityName(v);
+		} else if (is_new) {
+			s.priority = "normal";
+		}
+	}
+	{
+		bool v = false;
+		if (st->AssignIfExist(EC_TAG_SERVER_STATIC, v)) s.is_static = v;
+	}
+}
+
+}  // namespace
+
+
+void ApplyGetUpdateToServers(const CECPacket *resp,
+                             std::map<std::uint32_t, ServerSnapshot> &cache)
+{
+	if (!resp) return;
+	// Find the EC_TAG_SERVER container at top level. Unlike the
+	// legacy `EC_OP_GET_SERVER_LIST` shape (one EC_TAG_SERVER per
+	// server at the response root), GET_UPDATE wraps the per-server
+	// tags in one CECEmptyTag container — same `EC_TAG_SERVER` name
+	// for the container itself. We iterate INTO the container.
+	const CECTag *container = resp->GetTagByName(EC_TAG_SERVER);
+	if (!container) return;
+
+	// The container always carries the FULL current server list (no
+	// FILE_REMOVED markers for servers on the server side — see
+	// ExternalConn.cpp:985-994), but individual per-server fields are
+	// CValueMap-suppressed on unchanged values. Two consequences:
+	//  1. Servers absent from the response are gone on amuled's
+	//     side — we evict by "not seen this tick".
+	//  2. For servers we already cache, identity tags may be absent
+	//     this tick; MergeServerTag leaves cached values intact
+	//     (the `if (is_new || !n.empty())` guard).
+	std::set<std::uint32_t> seen;
+	for (CECTag::const_iterator it = container->begin();
+	     it != container->end(); ++it) {
+		const CECTag *t = &*it;
+		if (t->GetTagName() != EC_TAG_SERVER) continue;
+		const CEC_Server_Tag *st = static_cast<const CEC_Server_Tag *>(t);
+		const std::uint32_t ecid = st->ID();
+		seen.insert(ecid);
+
+		auto map_it = cache.find(ecid);
+		if (map_it == cache.end()) {
+			ServerSnapshot fresh;
+			MergeServerTag(st, fresh, /*is_new=*/true);
+			cache.emplace(ecid, std::move(fresh));
+		} else {
+			MergeServerTag(st, map_it->second, /*is_new=*/false);
+		}
+	}
+
+	// Evict cache entries we didn't see this tick — they're gone on
+	// the amuled side (operator removed them, or a fresh connection
+	// is rebuilding the list from a different serverlist source).
+	for (auto it = cache.begin(); it != cache.end();) {
+		if (seen.find(it->first) == seen.end()) {
+			it = cache.erase(it);
+		} else {
+			++it;
+		}
+	}
+}
+
+
+// --- /stats/tree -------------------------------------------------------
+
+namespace {
+
+void ParseStatsTreeNode(const CECTag *node, StatsTreeNode &out)
+{
+	const CEC_StatTree_Node_Tag *n =
+		static_cast<const CEC_StatTree_Node_Tag *>(node);
+	out.label = std::string(n->GetDisplayString().utf8_str());
+	for (CECTag::const_iterator it = n->begin(); it != n->end(); ++it) {
+		if (it->GetTagName() != EC_TAG_STATTREE_NODE) continue;
+		StatsTreeNode child;
+		ParseStatsTreeNode(&*it, child);
+		out.children.push_back(std::move(child));
+	}
+}
+
+}  // namespace
+
+
+void ParseStatsTreeFromPacket(const CECPacket *resp, StatsTreeNode &out)
+{
+	out.label.clear();
+	out.children.clear();
+	if (!resp) return;
+	// amuled emits a single root EC_TAG_STATTREE_NODE; its label is
+	// always an unlabeled container, so we drop it and surface its
+	// direct children at the top level. This matches what amuleweb's
+	// `am_load_stats_tree.php` does and what the reference REST
+	// branch's /stats/tree handler does.
+	const CECTag *root = resp->GetTagByName(EC_TAG_STATTREE_NODE);
+	if (!root) return;
+	for (CECTag::const_iterator it = root->begin(); it != root->end(); ++it) {
+		if (it->GetTagName() != EC_TAG_STATTREE_NODE) continue;
+		StatsTreeNode child;
+		ParseStatsTreeNode(&*it, child);
+		out.children.push_back(std::move(child));
+	}
+}
+
+
+// --- /stats/graphs/{graph} --------------------------------------------
+
+namespace {
+
+// EC_TAG_STATSGRAPH_DATA is a binary blob of N interleaved uint32
+// channels, each value pre-converted to network byte order via
+// `ENDIAN_HTONL` on the amuled side (Statistics.cpp:621-624). We
+// have to byte-swap back to host order before consumption — `ntohl`
+// is a no-op on big-endian hosts and the canonical 4-byte swap on
+// little-endian, which is what every modern target (x86_64, arm64)
+// runs.
+std::uint32_t BigEndianToHost32(const std::uint8_t *p)
+{
+	return  (static_cast<std::uint32_t>(p[0]) << 24)
+	      | (static_cast<std::uint32_t>(p[1]) << 16)
+	      | (static_cast<std::uint32_t>(p[2]) <<  8)
+	      | (static_cast<std::uint32_t>(p[3]));
+}
+
+void UnpackInterleavedUint32(const std::uint8_t *bytes, std::size_t byte_len,
+                             unsigned num_channels,
+                             std::vector<std::vector<std::uint32_t>> &out_channels)
+{
+	out_channels.assign(num_channels, std::vector<std::uint32_t>{});
+	if (!bytes || byte_len == 0 || num_channels == 0) return;
+	const std::size_t total_u32s = byte_len / sizeof(std::uint32_t);
+	const std::size_t num_points = total_u32s / num_channels;
+	for (unsigned c = 0; c < num_channels; ++c) {
+		out_channels[c].reserve(num_points);
+	}
+	for (std::size_t p = 0; p < num_points; ++p) {
+		for (unsigned c = 0; c < num_channels; ++c) {
+			out_channels[c].push_back(BigEndianToHost32(
+				bytes + (p * num_channels + c) * sizeof(std::uint32_t)));
+		}
+	}
+}
+
+}  // namespace
+
+
+void ParseGraphsFromPacket(const CECPacket *resp, StatsGraphs &out)
+{
+	out = StatsGraphs{};
+	if (!resp) return;
+
+	if (const CECTag *t = resp->GetTagByName(EC_TAG_STATSGRAPH_DATA)) {
+		// 4 interleaved channels per amuled-side layout
+		// (Statistics.cpp:621-624):
+		//  ch0 = kBpsDownCur * 1024  (bytes per second)
+		//  ch1 = kBpsUpCur   * 1024  (bytes per second)
+		//  ch2 = cntConnections      (active client connections)
+		//  ch3 = kadNodesCur         (Kad nodes currently routed)
+		std::vector<std::vector<std::uint32_t>> channels;
+		UnpackInterleavedUint32(
+			static_cast<const std::uint8_t *>(t->GetTagData()),
+			t->GetTagDataLen(), /*num_channels=*/4, channels);
+		if (channels.size() >= 4) {
+			out.download_bps = std::move(channels[0]);
+			out.upload_bps   = std::move(channels[1]);
+			out.connections  = std::move(channels[2]);
+			out.kad_nodes    = std::move(channels[3]);
+		}
+	}
+	// EC_TAG_STATSGRAPH_DATA_CONN carries the upload-slot / download-
+	// slot counts (2 interleaved channels) — useful for the dashboard
+	// graph but not in StatsGraphs surface yet. Skipping until a
+	// concrete client asks; the EC bytes still travel for free since
+	// they're in the same response.
+	if (const CECTag *t = resp->GetTagByName(EC_TAG_STATSGRAPH_SESSION_DL)) {
+		out.session_download_bytes = static_cast<std::uint64_t>(t->GetInt());
+	}
+	if (const CECTag *t = resp->GetTagByName(EC_TAG_STATSGRAPH_SESSION_UL)) {
+		out.session_upload_bytes   = static_cast<std::uint64_t>(t->GetInt());
+	}
+	if (const CECTag *t = resp->GetTagByName(EC_TAG_STATSGRAPH_SESSION_KAD)) {
+		out.session_kad_bytes      = static_cast<std::uint64_t>(t->GetInt());
+	}
+}
+
+
+// --- /search/results (full fetch per tick) -----------------------------
+
+void ApplySearchFull(const CECPacket *resp,
+                     std::map<std::uint32_t, SearchResult> &cache)
+{
+	cache.clear();
+	if (!resp) return;
+	for (CECPacket::const_iterator it = resp->begin(); it != resp->end(); ++it) {
+		const CECTag *t = &*it;
+		if (t->GetTagName() != EC_TAG_SEARCHFILE) continue;
+		const CEC_SearchFile_Tag *sf =
+			static_cast<const CEC_SearchFile_Tag *>(t);
+		SearchResult r;
+		r.ecid = sf->ID();
+		{
+			std::string h(sf->FileHashString().utf8_str());
+			std::transform(h.begin(), h.end(), h.begin(),
+				[](unsigned char c) { return std::tolower(c); });
+			r.hash = std::move(h);
+		}
+		r.name = std::string(sf->FileName().utf8_str());
+		r.size = sf->SizeFull();
+		{
+			std::uint32_t v = 0;
+			if (sf->AssignIfExist(EC_TAG_PARTFILE_SOURCE_COUNT, v))
+				r.source_count = v;
+		}
+		{
+			std::uint32_t v = 0;
+			if (sf->AssignIfExist(EC_TAG_PARTFILE_SOURCE_COUNT_XFER, v))
+				r.complete_source_count = v;
+		}
+		r.already_have = sf->AlreadyHave();
+		{
+			std::uint8_t v = 0;
+			if (sf->AssignIfExist(EC_TAG_KNOWNFILE_RATING, v)) r.rating = v;
+		}
+		cache.emplace(r.ecid, std::move(r));
+	}
+}
+
+
+// --- Search-progress, daemon-supplied lifecycle path -------------------
+//
+// Reads EC_TAG_SEARCH_LIFECYCLE_STATE from the EC_OP_SEARCH_PROGRESS
+// response — the unambiguous lifecycle tag landed alongside this PR.
+// No sentinel decode, no `saw_in_progress` tracking, no defensive
+// timeout: the daemon's flag is the source of truth. amuleapi pins a
+// daemon version that carries the new tags, so this is the only path.
+SearchProgressSnapshot AdvanceSearchProgress(
+	const SearchProgressSnapshot &prev,
+	std::uint32_t lifecycle_state,
+	std::uint32_t pct_now)
+{
+	SearchProgressSnapshot next = prev;
+	if (lifecycle_state == 2 /* SEARCH_LIFECYCLE_FINISHED */) {
+		next.percent  = 100;
+		next.complete = true;
+		next.active   = false;
+	} else if (lifecycle_state == 1 /* SEARCH_LIFECYCLE_RUNNING */) {
+		next.complete = false;
+		next.active   = true;
+		// Unified 0..100 the daemon already computed for this search kind
+		// (global = real server-queue percent; Kad = cosmetic time-ramp;
+		// local = instantaneous). No kind special-casing here anymore.
+		next.percent  = (pct_now > 100) ? 100 : pct_now;
+	} else {
+		// SEARCH_LIFECYCLE_IDLE — refresher shouldn't be calling us
+		// in this state (active was true on entry), but stay defensive.
+		next.complete = false;
+		next.active   = false;
+		next.percent  = 0;
+	}
+	return next;
+}
+
+
+// --- /preferences + /categories (one EC roundtrip) ---------------------
+
+namespace {
+
+void ParseCategoryTag(const CECTag *cat_tag, CategorySnapshot &c)
+{
+	const CEC_Category_Tag *ct = static_cast<const CEC_Category_Tag *>(cat_tag);
+	// Category index lives in the tag's int payload (set by
+	// `CECTag(name, cat_index)` at construction — see
+	// `ECSpecialCoreTags.cpp` category ctor).
+	c.index = static_cast<std::uint32_t>(ct->GetInt());
+	c.name  = std::string(ct->Name().utf8_str());
+	c.path  = std::string(ct->Path().utf8_str());
+	c.comment = std::string(ct->Comment().utf8_str());
+	c.color   = ct->Color();
+	c.priority_code = ct->Prio();
+	// Reuse the download-priority namer — categories use the same
+	// PR_* code space.
+	{
+		bool _ignore = false;
+		c.priority = DownloadPriorityName(c.priority_code, _ignore);
+	}
+}
+
+
+void ParseGeneralPrefs(const CECTag *gen, PreferencesSnapshot &out)
+{
+	if (const CECTag *t = gen->GetTagByName(EC_TAG_USER_NICK)) {
+		out.nickname = std::string(t->GetStringData().utf8_str());
+	}
+	if (const CECTag *t = gen->GetTagByName(EC_TAG_USER_HASH)) {
+		out.user_hash = std::string(
+			t->GetMD4Data().Encode().Lower().utf8_str());
+	}
+	if (const CECTag *t = gen->GetTagByName(EC_TAG_USER_HOST)) {
+		out.host_name = std::string(t->GetStringData().utf8_str());
+	}
+	if (gen->GetTagByName(EC_TAG_GENERAL_CHECK_NEW_VERSION)) {
+		out.check_new_version = true;
+	}
+}
+
+
+void ParseConnectionPrefs(const CECTag *conn, PreferencesSnapshot &out)
+{
+	if (const CECTag *t = conn->GetTagByName(EC_TAG_CONN_UL_CAP)) {
+		out.max_upload_cap_kbps = static_cast<std::uint32_t>(t->GetInt());
+	}
+	if (const CECTag *t = conn->GetTagByName(EC_TAG_CONN_DL_CAP)) {
+		out.max_download_cap_kbps = static_cast<std::uint32_t>(t->GetInt());
+	}
+	if (const CECTag *t = conn->GetTagByName(EC_TAG_CONN_MAX_UL)) {
+		out.max_upload_kbps = static_cast<std::uint32_t>(t->GetInt());
+	}
+	if (const CECTag *t = conn->GetTagByName(EC_TAG_CONN_MAX_DL)) {
+		out.max_download_kbps = static_cast<std::uint32_t>(t->GetInt());
+	}
+	if (const CECTag *t = conn->GetTagByName(EC_TAG_CONN_SLOT_ALLOCATION)) {
+		out.slot_allocation = static_cast<std::uint32_t>(t->GetInt());
+	}
+	if (const CECTag *t = conn->GetTagByName(EC_TAG_CONN_TCP_PORT)) {
+		out.tcp_port = static_cast<std::uint16_t>(t->GetInt());
+	}
+	if (const CECTag *t = conn->GetTagByName(EC_TAG_CONN_UDP_PORT)) {
+		out.udp_port = static_cast<std::uint16_t>(t->GetInt());
+	}
+	// The EmptyTag markers (presence = true, absence = false).
+	out.udp_disabled  = conn->GetTagByName(EC_TAG_CONN_UDP_DISABLE) != nullptr;
+	out.autoconnect   = conn->GetTagByName(EC_TAG_CONN_AUTOCONNECT) != nullptr;
+	out.reconnect     = conn->GetTagByName(EC_TAG_CONN_RECONNECT)   != nullptr;
+	out.network_ed2k  = conn->GetTagByName(EC_TAG_NETWORK_ED2K)     != nullptr;
+	out.network_kad   = conn->GetTagByName(EC_TAG_NETWORK_KADEMLIA) != nullptr;
+
+	if (const CECTag *t = conn->GetTagByName(EC_TAG_CONN_MAX_FILE_SOURCES)) {
+		out.max_sources_per_file = static_cast<std::uint32_t>(t->GetInt());
+	}
+	if (const CECTag *t = conn->GetTagByName(EC_TAG_CONN_MAX_CONN)) {
+		out.max_connections = static_cast<std::uint32_t>(t->GetInt());
+	}
+}
+
+}  // namespace
+
+
+void ParsePreferencesFromPacket(const CECPacket *resp,
+                                PreferencesSnapshot &out_prefs,
+                                std::vector<CategorySnapshot> &out_cats)
+{
+	out_cats.clear();
+	if (!resp) return;
+
+	// Each prefs sub-section is one top-level CECEmptyTag with named
+	// child fields. `EC_TAG_PREFS_CATEGORIES` wraps individual
+	// `EC_TAG_CATEGORY` entries (one per index).
+	if (const CECTag *gen = resp->GetTagByName(EC_TAG_PREFS_GENERAL)) {
+		ParseGeneralPrefs(gen, out_prefs);
+	}
+	if (const CECTag *conn = resp->GetTagByName(EC_TAG_PREFS_CONNECTIONS)) {
+		ParseConnectionPrefs(conn, out_prefs);
+	}
+	if (const CECTag *cats = resp->GetTagByName(EC_TAG_PREFS_CATEGORIES)) {
+		for (CECTag::const_iterator it = cats->begin(); it != cats->end(); ++it) {
+			const CECTag *cat = &*it;
+			if (cat->GetTagName() != EC_TAG_CATEGORY) continue;
+			CategorySnapshot c;
+			ParseCategoryTag(cat, c);
+			out_cats.push_back(std::move(c));
+		}
+	}
+}
+
+
+// RefresherTick + TwoPhaseRefresh live in RefresherTick.cpp so that
+// this TU stays App-free and the unit tests can link the Apply*
+// functions without pulling in wxApp / ExternalConnector.
+
+
+}  // namespace webapi
diff --git a/src/webapi/Refresher.h b/src/webapi/Refresher.h
new file mode 100644
index 0000000000..2c57c3b8c2
--- /dev/null
+++ b/src/webapi/Refresher.h
@@ -0,0 +1,226 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#ifndef WEBAPI_REFRESHER_H
+#define WEBAPI_REFRESHER_H
+
+#include <cstdint>
+#include <ctime>      // std::time_t — needed for AdvanceSearchProgress
+#include <map>
+#include <string>
+#include <vector>
+
+
+class CECPacket;
+class CamuleapiApp;
+class PartFileEncoderData;
+
+
+namespace webapi {
+
+
+class CState;
+
+
+// Single tick of the EC poller. Issues every cached request, parses
+// each response into a snapshot struct, writes it under CState's
+// exclusive lock. Returns true on success, false if any EC roundtrip
+// failed (caller flips CState::MarkTickFailure and leaves stale
+// data in place).
+//
+// Runs on the wxApp thread (same thread CRemoteConnect uses for its
+// socket I/O), so it can issue the EC roundtrip synchronously without
+// thread-marshalling. Mutation handlers on the HTTP threads reach EC
+// through a process-wide mutex around `CamuleapiApp::SendRecvMsg_v2`,
+// so refresher + mutations share the same EC-traffic budget.
+//
+// Pure-function shape (app + state by reference, returns bool) so the
+// tick body is unit-testable against a mock EC reply.
+bool RefresherTick(CamuleapiApp &app, CState &state);
+
+// Single-threaded SSE diff emission. Called ONLY from the wxApp
+// refresher loop after a successful RefresherTick so that the
+// LastSeenState walk (which mutates app.LastSeenForEvents()) is
+// single-writer. Inline-from-HTTP RefresherTick call sites
+// deliberately skip it — SSE subscribers see the post-mutation
+// diff on the next 1-second tick instead of immediately.
+void EmitDiffsForEventBus(CamuleapiApp &app, const CState &state);
+
+
+// Sub-tick helpers exposed for testing. The Refresher uses these
+// internally; the unit test calls them against hand-crafted
+// CECPacket fixtures to pin the EC-tag-to-State mapping without
+// standing up a real amuled.
+
+struct StatusSnapshot;
+struct FileSnapshot;
+struct ClientSnapshot;
+struct ServerSnapshot;
+struct KadSnapshot;
+struct CategorySnapshot;
+struct PreferencesSnapshot;
+class  FileMap;
+
+void ParseStatusFromPacket(const CECPacket *resp, StatusSnapshot &out);
+// Kad detail rides the same STAT_REQ response — saves a roundtrip
+// since amuled bundles `EC_TAG_STATS_KAD_*` into the standard CMD-
+// level stats packet. /status calls ParseStatus then /kad calls
+// this against the same packet pointer.
+void ParseKadFromPacket   (const CECPacket *resp, KadSnapshot &out);
+
+// Drain new amule-log lines from the STAT_REQ response. amule's EC
+// server piggybacks them inside an `EC_TAG_STATS_LOGGER_MESSAGE`
+// parent tag with child `EC_TAG_STRING` tags, but ONLY when the
+// STAT_REQ was issued at `EC_DETAIL_FULL` (or INC_UPDATE). The
+// refresher calls this on the same packet as ParseStatus / ParseKad,
+// then `state.AppendAmuleLog(...)` to fold them into the cache.
+void ParseAmuleLogFromPacket(const CECPacket *resp,
+                             std::vector<std::string> &out_new_lines);
+
+// `EC_OP_GET_PREFERENCES` response → flat prefs + bundled categories
+// (the EC packet carries categories under `EC_TAG_PREFS_CATEGORIES`).
+// One roundtrip populates both /preferences and /categories.
+void ParsePreferencesFromPacket(const CECPacket *resp,
+                                PreferencesSnapshot &out_prefs,
+                                std::vector<CategorySnapshot> &out_cats);
+
+// `EC_OP_GET_UPDATE` at `EC_DETAIL_INC_UPDATE` is the consolidated
+// fetch backing downloads + shared + servers in a single roundtrip.
+// Response shape (ExternalConn.cpp:869):
+//  * top-level interleaved `EC_TAG_PARTFILE` (downloads) and
+//    `EC_TAG_KNOWNFILE` (shared) — full identity on first encounter,
+//    stat-only deltas on subsequent ticks via server-side valuemap.
+//  * top-level `EC_TAG_FILE_REMOVED` markers for both caches (the
+//    encoder map is unified server-side).
+//  * `EC_TAG_SERVER` container — full list every tick, valuemap-
+//    suppressed unchanged per-server fields.
+//  * `EC_TAG_CLIENT` container — IGNORED in favour of
+//    `EC_OP_GET_ULOAD_QUEUE` so /uploads stays bound to the upload-
+//    queue semantic (the GET_UPDATE clients block is filtered by
+//    the global `TransmitOnlyUploadingClients` pref which would
+//    pollute amuleweb/amulegui's view).
+//  * `EC_TAG_FRIEND` container — IGNORED.
+//
+// Why INC_UPDATE instead of per-substruct UPDATE: the per-substruct
+// paths at `EC_DETAIL_UPDATE` strip identity (ECSpecialCoreTags.cpp:
+// 244-246's early-return), forcing the second FULL-detail roundtrip
+// the old refresher used. INC_UPDATE doesn't hit that early-return —
+// identity arrives in one shot, no follow-up needed, no #713 / #808
+// defences (those wire-level races only exist at EC_DETAIL_UPDATE).
+//
+// The three helpers below each iterate the same response once,
+// filtering for their tag type. Called under three distinct CState
+// mutator acquisitions; snapshot_at is set after the whole tick
+// succeeds, so cross-substruct consistency is best-effort.
+
+// Merges download-walker state (EC_TAG_PARTFILE children) into the
+// unified file map. Sets `is_downloading=true` on touched entries,
+// writes only the download sub-block. FILE_REMOVED clears the
+// download role (and drops the entry entirely if `is_shared` was
+// also false). See FileSnapshot in State.h for the unified-map
+// rationale.
+void ApplyGetUpdateToDownloads(
+	const CECPacket *resp,
+	FileMap &cache,
+	std::map<std::uint32_t, PartFileEncoderData> &rle_state);
+
+// Merges shared-walker state (EC_TAG_KNOWNFILE / EC_TAG_PARTFILE with
+// SHARED flag) into the same unified map. Sets `is_shared=true`,
+// updates the shared sub-block, and clears the shared role on
+// PARTFILE_SHARED=false / FILE_REMOVED. The dl_identity_fallback
+// parameter is gone: when the shared walker sees a partfile whose
+// hash tag was CValueMap-suppressed, the entry already carries hash
+// + name from the downloads walker on the same tick (same unified
+// map), so the shared walker just flips its flag and merges its own
+// fields. No fallback hop needed.
+void ApplyGetUpdateToShared(
+	const CECPacket *resp,
+	FileMap &cache);
+
+void ApplyGetUpdateToServers(
+	const CECPacket *resp,
+	std::map<std::uint32_t, ServerSnapshot>   &cache);
+
+
+// /stats/tree (EC_OP_GET_STATSTREE response). Recursive walk —
+// every EC_TAG_STATTREE_NODE that contains children becomes a
+// branch; leaves get `children.empty()`. The top-level `root` is
+// an unnamed container; we skip the root and emit its direct
+// children as the visible tree (matches amuleweb's
+// `am_load_stats_tree.php` behaviour).
+struct StatsTreeNode;
+void ParseStatsTreeFromPacket(const CECPacket *resp, StatsTreeNode &out);
+
+// /stats/graphs/{graph} (EC_OP_GET_STATSGRAPHS response). amuled
+// packs the four time-series (download/upload/connections+kad as
+// two interleaved channels in EC_TAG_STATSGRAPH_DATA + a separate
+// EC_TAG_STATSGRAPH_DATA_CONN) into byte blobs. Parser un-packs
+// them into the four separate vectors of `StatsGraphs`.
+struct StatsGraphs;
+void ParseGraphsFromPacket(const CECPacket *resp, StatsGraphs &out);
+
+// /search/results (EC_OP_SEARCH_RESULTS response). Full-state fetch
+// per tick; like /servers, no INC path exists for the search list.
+// Cache is keyed by ECID; cleared on each refresher tick before
+// applying.
+struct SearchResult;
+void ApplySearchFull(const CECPacket *resp,
+                     std::map<std::uint32_t, SearchResult> &cache);
+
+
+// Search-progress derivation from the EC_TAG_SEARCH_LIFECYCLE_* tags.
+// `lifecycle_state` is the uint8 enum value (0=idle, 1=running,
+// 2=finished). `pct_now` is the EC_TAG_SEARCH_LIFECYCLE_PERCENT value —
+// the daemon's unified 0..100 for every search kind (global = real,
+// Kad = cosmetic ramp, finished = 100), passed straight through (no
+// per-kind masking). Pure function: no I/O, no globals — RefresherTest
+// exercises every branch without standing up a daemon.
+struct SearchProgressSnapshot;
+SearchProgressSnapshot AdvanceSearchProgress(
+	const SearchProgressSnapshot &prev,
+	std::uint32_t lifecycle_state,
+	std::uint32_t pct_now);
+
+// `ApplyGetUpdateToClients` consumes the EC_TAG_CLIENT container
+// from the consolidated GET_UPDATE response. The walker uses
+// "seen-this-tick = keep, absent = evict" semantics: every alive
+// client surfaces every tick via the outer per-client tag (CValueMap
+// suppression operates on the tag's *children*, not on the entity
+// itself), so cache entries not seen in this response are gone on
+// amuled's side (peer disconnected, dropped from queue, banned).
+// `file_hash_by_ecid` lets the walker resolve EC_TAG_CLIENT_UPLOAD_FILE
+// / EC_TAG_CLIENT_REQUEST_FILE (raw amuled ECIDs) into MD4 hashes
+// at walker time, so ClientSnapshot can surface the hash directly.
+// Build it from the unified file map AFTER the downloads/shared
+// walkers have run on the same tick. Empty map = correlator hashes
+// stay empty (matches "not currently transferring" semantics).
+void ApplyGetUpdateToClients(
+	const CECPacket *resp,
+	std::map<std::uint32_t, ClientSnapshot>   &cache,
+	const std::map<std::uint32_t, std::string> &file_hash_by_ecid);
+
+
+}  // namespace webapi
+
+#endif // WEBAPI_REFRESHER_H
diff --git a/src/webapi/RefresherTick.cpp b/src/webapi/RefresherTick.cpp
new file mode 100644
index 0000000000..2a63ee414f
--- /dev/null
+++ b/src/webapi/RefresherTick.cpp
@@ -0,0 +1,256 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+// Refresher orchestration — the per-tick loop body that issues EC
+// requests via `CamuleapiApp::SendRecvSerialized`. Split from
+// Refresher.cpp so the pure parser/applier code (`ApplyDownloads*`,
+// `ApplyUploads*`, `ApplyShared*`, `ParseStatusFromPacket`) stays
+// linkable from the unit tests without dragging the wxApp /
+// ExternalConnector dependency tree in via App.h.
+
+#include "Refresher.h"
+
+#include "App.h"
+#include "EventDiff.h"
+#include "State.h"
+
+#include <ec/cpp/ECSpecialTags.h>
+#include <ec/cpp/ECPacket.h>
+
+#include <cstdint>
+#include <map>
+#include <memory>
+#include <set>
+
+
+namespace webapi {
+
+
+bool RefresherTick(CamuleapiApp &app, CState &state)
+{
+	// Per-tick budget: a few EC ops via SendRecvSerialized
+	// (m_ec_mtx-serialised). Any failure bails the whole tick so the
+	// cache stays internally consistent — we never expose
+	// partially-refreshed snapshots. STAT_REQ runs first because
+	// it's the cheapest probe: if EC dropped between ticks, STAT_REQ
+	// catches it before we burn roundtrips on the larger queries.
+
+	// /status + /kad + /logs/amule share one STAT_REQ packet.
+	//
+	// Detail level CMD → FULL because amuled only piggybacks
+	// `EC_TAG_STATS_LOGGER_MESSAGE` (the incremental-log channel) at
+	// FULL or INC_UPDATE (ExternalConn.cpp:722-730). FULL also adds
+	// a few stat-overhead extras (STATS_UP_OVERHEAD,
+	// STATS_DOWN_OVERHEAD, STATS_BANNED_COUNT, STATS_TOTAL_*_BYTES,
+	// STATS_SHARED_FILE_COUNT) that StatusSnapshot doesn't yet
+	// surface — harmless overhead.
+	{
+		std::unique_ptr<CECPacket> req(new CECPacket(EC_OP_STAT_REQ, EC_DETAIL_FULL));
+		const CECPacket *resp = app.SendRecvSerialized(req.get());
+		if (!resp) return false;
+		StatusSnapshot s;
+		ParseStatusFromPacket(resp, s);
+		state.WriteStatus(std::move(s));
+		KadSnapshot k;
+		ParseKadFromPacket(resp, k);
+		state.WriteKad(std::move(k));
+		std::vector<std::string> new_log_lines;
+		ParseAmuleLogFromPacket(resp, new_log_lines);
+		if (!new_log_lines.empty()) {
+			state.AppendAmuleLog(std::move(new_log_lines));
+		}
+		delete resp;
+	}
+
+	// /downloads + /shared + /servers in a single GET_UPDATE roundtrip
+	// at EC_DETAIL_INC_UPDATE. Replaces an earlier per-substruct
+	// fetch (GET_DLOAD_QUEUE + GET_SHARED_FILES + GET_SERVER_LIST,
+	// each with its own UPDATE+FULL two-pass split). Response packet
+	// shape and the "why INC_UPDATE works in one tick" rationale
+	// (identity short-circuit at EC_DETAIL_UPDATE only) are documented
+	// next to ApplyGetUpdateToDownloads in Refresher.h.
+	//
+	// The response also carries EC_TAG_CLIENT (filtered server-side
+	// by `TransmitOnlyUploadingClients`) and EC_TAG_FRIEND containers,
+	// both of which we ignore — /uploads stays bound to the upload-
+	// queue semantic via EC_OP_GET_ULOAD_QUEUE below.
+	//
+	// Three Mutate calls under three separate lock acquisitions —
+	// snapshot_at is set after the whole tick succeeds; per-substruct
+	// atomicity was already best-effort.
+	{
+		std::unique_ptr<CECPacket> req(
+			new CECPacket(EC_OP_GET_UPDATE, EC_DETAIL_INC_UPDATE));
+		const CECPacket *resp = app.SendRecvSerialized(req.get());
+		if (!resp) return false;
+		auto &rle = app.PartfileRleStateRequireStateWriteLock();
+
+		// Snapshot the cache's pre-tick ECID set so we can evict
+		// rle_state entries for any partfile that gets removed during
+		// the walk (the walker erases from rle_state on FILE_REMOVED,
+		// but we also want to cover the case where ApplyGetUpdate*
+		// itself evicts in some future hardening path).
+		std::set<std::uint32_t> ecids_before;
+		state.MutateDownloads(
+			[&](FileMap &cache) {
+				for (const auto &kv : cache) {
+					if (kv.second.is_downloading) ecids_before.insert(kv.first);
+				}
+				ApplyGetUpdateToDownloads(resp, cache, rle);
+				// Evict RLE state for ECIDs that no longer carry the
+				// downloading role after the apply. The walker handles
+				// FILE_REMOVED already; this is defence in depth.
+				for (auto ecid : ecids_before) {
+					auto it = cache.find(ecid);
+					if (it == cache.end() || !it->second.is_downloading) {
+						rle.erase(ecid);
+					}
+				}
+			});
+
+		// Shared walker reads + writes the same unified m_files map.
+		// No more dl_identity_fallback compose: when the shared walker
+		// sees a partfile whose hash was CValueMap-suppressed, the
+		// entry in `cache` already carries hash + name from the
+		// downloads walker above. See FileSnapshot in State.h for the
+		// shared-storage rationale.
+		state.MutateShared(
+			[&](FileMap &cache) {
+				ApplyGetUpdateToShared(resp, cache);
+			});
+
+		state.MutateServers(
+			[&](std::map<std::uint32_t, ServerSnapshot> &cache) {
+				ApplyGetUpdateToServers(resp, cache);
+			});
+
+		// /clients — every alive peer in theApp->clientlist (download
+		// sources, upload slots, queue waiters, etc.). Build an
+		// ecid→hash snapshot from the unified file map first so the
+		// clients walker can resolve EC_TAG_CLIENT_UPLOAD_FILE /
+		// REQUEST_FILE into MD4 hashes at walker time (the wire
+		// contract is hash-only — ECIDs never leak out).
+		std::map<std::uint32_t, std::string> file_hash_by_ecid;
+		for (const auto &f : state.Files()) {
+			if (!f.hash.empty()) file_hash_by_ecid.emplace(f.ecid, f.hash);
+		}
+		state.MutateClients(
+			[&](std::map<std::uint32_t, ClientSnapshot> &cache) {
+				ApplyGetUpdateToClients(resp, cache, file_hash_by_ecid);
+			});
+		delete resp;
+	}
+
+	// /logs/serverinfo, /stats/tree, /stats/graphs/{graph} are NOT
+	// fetched per-tick — they're lazy-fetched on first GET via
+	// CTtlCache (1 s TTL coalesces burst reads). HTTP handlers in
+	// Api.cpp drive their own EC roundtrips under m_ec_mtx. Per-tick
+	// refresh would have been pure waste when nothing is listening.
+
+	// /search/results — polled per-tick only WHILE a search is active.
+	// POST /search flips state.SearchProgress().active = true; the
+	// daemon's EC_TAG_SEARCH_LIFECYCLE_STATE tells us when to flip it
+	// back. amuleapi pins a daemon version carrying the new lifecycle
+	// tags, so we read them directly with no sentinel-decode fallback.
+	if (state.SearchProgress().active) {
+		std::uint32_t percent         = 0;
+		std::uint32_t lifecycle_state = 0;
+		{
+			std::unique_ptr<CECPacket> req(
+				new CECPacket(EC_OP_SEARCH_RESULTS, EC_DETAIL_FULL));
+			const CECPacket *resp = app.SendRecvSerialized(req.get());
+			if (!resp) return false;
+			state.MutateSearch(
+				[&](std::map<std::uint32_t, SearchResult> &cache) {
+					ApplySearchFull(resp, cache);
+				});
+			delete resp;
+		}
+		{
+			std::unique_ptr<CECPacket> req(
+				new CECPacket(EC_OP_SEARCH_PROGRESS));
+			const CECPacket *resp = app.SendRecvSerialized(req.get());
+			if (resp) {
+				// Unified 0..100 the daemon computes for every search kind
+				// (global = real, Kad = cosmetic ramp, finished = 100).
+				// No longer decoding EC_TAG_SEARCH_STATUS's overloaded sentinels.
+				if (const CECTag *t = resp->GetTagByName(EC_TAG_SEARCH_LIFECYCLE_PERCENT)) {
+					percent = static_cast<std::uint32_t>(t->GetInt());
+				}
+				if (const CECTag *t = resp->GetTagByName(EC_TAG_SEARCH_LIFECYCLE_STATE)) {
+					lifecycle_state = static_cast<std::uint32_t>(t->GetInt());
+				}
+				delete resp;
+			}
+		}
+		const SearchProgressSnapshot next = AdvanceSearchProgress(
+			state.SearchProgress(), lifecycle_state, percent);
+		state.WriteSearchProgress(next);
+	}
+
+	// /preferences + /categories — one EC roundtrip populates both.
+	// Selection bitmask: CATEGORIES (0x01) + GENERAL (0x02) +
+	// CONNECTIONS (0x04). Using the named enums (rather than hex
+	// literals) so a future bit shuffle in ECCodes.h doesn't
+	// silently zero out a section — bit-positional bugs here are
+	// hard to spot in JSON (empty defaults look like "0 KB/s" not
+	// "field not requested").
+	{
+		const std::uint32_t selection =
+			EC_PREFS_CATEGORIES | EC_PREFS_GENERAL | EC_PREFS_CONNECTIONS;
+		std::unique_ptr<CECPacket> req(new CECPacket(EC_OP_GET_PREFERENCES));
+		req->AddTag(CECTag(EC_TAG_SELECT_PREFS, selection));
+		const CECPacket *resp = app.SendRecvSerialized(req.get());
+		if (!resp) return false;
+		PreferencesSnapshot p;
+		std::vector<CategorySnapshot> cats;
+		ParsePreferencesFromPacket(resp, p, cats);
+		state.WritePreferences(std::move(p));
+		state.WriteCategories(std::move(cats));
+		delete resp;
+	}
+
+	// EmitDiffsAndUpdate is intentionally NOT called here. Mutation
+	// handlers invoke RefresherTick() inline on HTTP threads so the
+	// response sees post-mutation state, and LastSeenState has no
+	// internal lock — concurrent std::map mutation from the wxApp
+	// refresher loop and an HTTP thread is UB. Only the wxApp loop
+	// in App.cpp calls EmitDiffsForEventBus() (below) after a
+	// successful tick; HTTP callers skip it and SSE subscribers see
+	// the diff on the next natural 1 s tick.
+	return true;
+}
+
+
+void EmitDiffsForEventBus(CamuleapiApp &app, const CState &state)
+{
+	// Sole writer of `app.LastSeenForEvents()`. ONLY the wxApp
+	// refresher loop calls this; HTTP-server inline RefresherTick
+	// call sites do NOT.
+	EmitDiffsAndUpdate(app.EventBus(),
+	                   app.LastSeenForEvents(),
+	                   state);
+}
+
+
+}  // namespace webapi
diff --git a/src/webapi/State.cpp b/src/webapi/State.cpp
new file mode 100644
index 0000000000..fdfd64c84a
--- /dev/null
+++ b/src/webapi/State.cpp
@@ -0,0 +1,428 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#include "State.h"
+
+#include <mutex>
+#include <shared_mutex>
+#include <utility>
+
+
+namespace webapi {
+
+
+bool CState::HasFirstSnapshot() const
+{
+	std::shared_lock<std::shared_timed_mutex> lock(m_mu);
+	return m_has_first_snapshot;
+}
+
+
+std::time_t CState::SnapshotAt() const
+{
+	std::shared_lock<std::shared_timed_mutex> lock(m_mu);
+	return m_snapshot_at;
+}
+
+
+bool CState::EcConnected() const
+{
+	std::shared_lock<std::shared_timed_mutex> lock(m_mu);
+	return m_ec_connected;
+}
+
+
+StatusSnapshot CState::Status() const
+{
+	std::shared_lock<std::shared_timed_mutex> lock(m_mu);
+	return m_status;
+}
+
+
+KadSnapshot CState::Kad() const
+{
+	std::shared_lock<std::shared_timed_mutex> lock(m_mu);
+	return m_kad;
+}
+
+
+CState::DashboardSnapshot CState::Dashboard() const
+{
+	// Single shared_lock acquisition: callers of /api/v0/status get
+	// a coherent (status, kad, snapshot_at, ec_connected) tuple
+	// instead of the four-separate-lock dance, which can interleave
+	// with a refresher tick and make `kad.network` describe a
+	// different tick than `ed2k.*` / `speeds.*`.
+	std::shared_lock<std::shared_timed_mutex> lock(m_mu);
+	DashboardSnapshot out;
+	out.status       = m_status;
+	out.kad          = m_kad;
+	out.snapshot_at  = m_snapshot_at;
+	out.ec_connected = m_ec_connected;
+	return out;
+}
+
+
+PreferencesSnapshot CState::Preferences() const
+{
+	std::shared_lock<std::shared_timed_mutex> lock(m_mu);
+	return m_preferences;
+}
+
+
+std::vector<CategorySnapshot> CState::Categories() const
+{
+	std::shared_lock<std::shared_timed_mutex> lock(m_mu);
+	return m_categories;
+}
+
+
+std::vector<std::string> CState::AmuleLog() const
+{
+	std::shared_lock<std::shared_timed_mutex> lock(m_mu);
+	return m_amule_log_lines;
+}
+
+
+ServerInfoLog CState::ServerInfo() const
+{
+	std::shared_lock<std::shared_timed_mutex> lock(m_mu);
+	return m_server_info;
+}
+
+
+StatsTreeNode CState::StatsTree() const
+{
+	std::shared_lock<std::shared_timed_mutex> lock(m_mu);
+	return m_stats_tree;
+}
+
+
+StatsGraphs CState::Graphs() const
+{
+	std::shared_lock<std::shared_timed_mutex> lock(m_mu);
+	return m_graphs;
+}
+
+
+std::vector<SearchResult> CState::Search() const
+{
+	std::shared_lock<std::shared_timed_mutex> lock(m_mu);
+	std::vector<SearchResult> out;
+	out.reserve(m_search.size());
+	for (const auto &kv : m_search) out.push_back(kv.second);
+	return out;
+}
+
+
+void CState::MutateSearch(const std::function<
+	void(std::map<std::uint32_t, SearchResult> &)> &fn)
+{
+	std::unique_lock<std::shared_timed_mutex> lock(m_mu);
+	fn(m_search);
+}
+
+
+SearchProgressSnapshot CState::SearchProgress() const
+{
+	std::shared_lock<std::shared_timed_mutex> lock(m_mu);
+	return m_search_progress;
+}
+
+
+void CState::MarkSearchStarted(const std::string &kind)
+{
+	std::unique_lock<std::shared_timed_mutex> lock(m_mu);
+	m_search.clear();
+	m_search_progress = SearchProgressSnapshot{};
+	m_search_progress.active = true;
+	m_search_progress.kind   = kind;
+}
+
+
+void CState::WriteSearchProgress(SearchProgressSnapshot s)
+{
+	std::unique_lock<std::shared_timed_mutex> lock(m_mu);
+	m_search_progress = std::move(s);
+}
+
+
+void CState::WriteStatsTree(StatsTreeNode t)
+{
+	std::unique_lock<std::shared_timed_mutex> lock(m_mu);
+	m_stats_tree = std::move(t);
+}
+
+
+void CState::WriteGraphs(StatsGraphs g)
+{
+	std::unique_lock<std::shared_timed_mutex> lock(m_mu);
+	m_graphs = std::move(g);
+}
+
+
+void CState::AppendAmuleLog(std::vector<std::string> new_lines)
+{
+	std::unique_lock<std::shared_timed_mutex> lock(m_mu);
+	// No cap — see State.h comment above the `m_amule_log_lines`
+	// declaration. Operators can truncate via DELETE /logs/amule
+	// .
+	m_amule_log_lines.insert(m_amule_log_lines.end(),
+		std::make_move_iterator(new_lines.begin()),
+		std::make_move_iterator(new_lines.end()));
+}
+
+
+void CState::ClearAmuleLog()
+{
+	std::unique_lock<std::shared_timed_mutex> lock(m_mu);
+	m_amule_log_lines.clear();
+}
+
+
+void CState::WriteServerInfo(ServerInfoLog s)
+{
+	std::unique_lock<std::shared_timed_mutex> lock(m_mu);
+	m_server_info = std::move(s);
+}
+
+
+std::vector<ServerSnapshot> CState::Servers() const
+{
+	std::shared_lock<std::shared_timed_mutex> lock(m_mu);
+	std::vector<ServerSnapshot> out;
+	out.reserve(m_servers.size());
+	for (const auto &kv : m_servers) out.push_back(kv.second);
+	return out;
+}
+
+
+void CState::WriteStatus(StatusSnapshot s)
+{
+	std::unique_lock<std::shared_timed_mutex> lock(m_mu);
+	m_status = std::move(s);
+}
+
+
+void CState::WriteKad(KadSnapshot k)
+{
+	std::unique_lock<std::shared_timed_mutex> lock(m_mu);
+	m_kad = std::move(k);
+}
+
+
+void CState::WritePreferences(PreferencesSnapshot p)
+{
+	std::unique_lock<std::shared_timed_mutex> lock(m_mu);
+	m_preferences = std::move(p);
+}
+
+
+void CState::WriteCategories(std::vector<CategorySnapshot> c)
+{
+	std::unique_lock<std::shared_timed_mutex> lock(m_mu);
+	m_categories = std::move(c);
+}
+
+
+void CState::MutateServers(const std::function<
+	void(std::map<std::uint32_t, ServerSnapshot> &)> &fn)
+{
+	std::unique_lock<std::shared_timed_mutex> lock(m_mu);
+	fn(m_servers);
+}
+
+
+std::vector<FileSnapshot> CState::Downloads() const
+{
+	std::shared_lock<std::shared_timed_mutex> lock(m_mu);
+	std::vector<FileSnapshot> out;
+	out.reserve(m_files.size());
+	for (const auto &kv : m_files) {
+		if (kv.second.is_downloading) out.push_back(kv.second);
+	}
+	return out;
+}
+
+
+std::vector<FileSnapshot> CState::Shared() const
+{
+	std::shared_lock<std::shared_timed_mutex> lock(m_mu);
+	std::vector<FileSnapshot> out;
+	out.reserve(m_files.size());
+	for (const auto &kv : m_files) {
+		if (kv.second.is_shared) out.push_back(kv.second);
+	}
+	return out;
+}
+
+
+std::vector<FileSnapshot> CState::Files() const
+{
+	std::shared_lock<std::shared_timed_mutex> lock(m_mu);
+	std::vector<FileSnapshot> out;
+	out.reserve(m_files.size());
+	for (const auto &kv : m_files) out.push_back(kv.second);
+	return out;
+}
+
+
+std::vector<ClientSnapshot> CState::Clients() const
+{
+	std::shared_lock<std::shared_timed_mutex> lock(m_mu);
+	std::vector<ClientSnapshot> out;
+	out.reserve(m_clients.size());
+	for (const auto &kv : m_clients) out.push_back(kv.second);
+	return out;
+}
+
+
+bool CState::FindDownload(const std::string &hash_hex,
+                          FileSnapshot &out) const
+{
+	std::shared_lock<std::shared_timed_mutex> lock(m_mu);
+	std::uint32_t ecid = 0;
+	if (!m_files.FindEcidByHash(hash_hex, ecid)) return false;
+	const auto it = m_files.find(ecid);
+	if (it == m_files.end() || !it->second.is_downloading) return false;
+	out = it->second;
+	return true;
+}
+
+
+bool CState::FindDownloadByEcid(std::uint32_t ecid,
+                                FileSnapshot &out) const
+{
+	std::shared_lock<std::shared_timed_mutex> lock(m_mu);
+	auto it = m_files.find(ecid);
+	if (it == m_files.end() || !it->second.is_downloading) return false;
+	out = it->second;
+	return true;
+}
+
+
+bool CState::FindShared(const std::string &hash_hex,
+                        FileSnapshot &out) const
+{
+	std::shared_lock<std::shared_timed_mutex> lock(m_mu);
+	std::uint32_t ecid = 0;
+	if (!m_files.FindEcidByHash(hash_hex, ecid)) return false;
+	const auto it = m_files.find(ecid);
+	if (it == m_files.end() || !it->second.is_shared) return false;
+	out = it->second;
+	return true;
+}
+
+
+bool CState::FindSharedByEcid(std::uint32_t ecid,
+                              FileSnapshot &out) const
+{
+	std::shared_lock<std::shared_timed_mutex> lock(m_mu);
+	auto it = m_files.find(ecid);
+	if (it == m_files.end() || !it->second.is_shared) return false;
+	out = it->second;
+	return true;
+}
+
+
+// MutateDownloads + MutateShared both lock + hand out m_files. Both
+// walkers operate on the same unified map (and the same lock acquisition,
+// when chained from a single tick); the callback decides which role
+// flag to set or clear. The FileMap wrapper keeps its hash→ECID index
+// in sync as the walker emplaces / erases, so there's no rebuild pass
+// at the end of the mutate window.
+void CState::MutateDownloads(const std::function<void(FileMap &)> &fn)
+{
+	std::unique_lock<std::shared_timed_mutex> lock(m_mu);
+	fn(m_files);
+}
+
+
+void CState::MutateShared(const std::function<void(FileMap &)> &fn)
+{
+	std::unique_lock<std::shared_timed_mutex> lock(m_mu);
+	fn(m_files);
+}
+
+
+void CState::MutateClients(const std::function<
+	void(std::map<std::uint32_t, ClientSnapshot> &)> &fn)
+{
+	std::unique_lock<std::shared_timed_mutex> lock(m_mu);
+	fn(m_clients);
+}
+
+
+void CState::ResetLists()
+{
+	std::unique_lock<std::shared_timed_mutex> lock(m_mu);
+	m_files.clear();
+	m_clients.clear();
+	m_servers.clear();
+	m_categories.clear();
+	m_search.clear();
+	m_search_progress = SearchProgressSnapshot{};
+	// Logs + stats_tree + graphs survive EC reconnects on purpose —
+	// operator can see "EC disconnected at HH:MM" alongside earlier
+	// graph traffic; stats_tree's counters are amuled-uptime not
+	// amuleapi-tick scoped.
+}
+
+
+void CState::MarkTickSuccess()
+{
+	std::unique_lock<std::shared_timed_mutex> lock(m_mu);
+	m_has_first_snapshot = true;
+	m_ec_connected       = true;
+	// `m_snapshot_at` is stamped at tick-END (here), not tick-start.
+	// Clients reading `snapshot_at` therefore see "the wall-clock
+	// moment the daemon finished assembling this snapshot", with the
+	// tick's own duration as the implicit skew (typically 50-200 ms,
+	// up to multi-second under EC-mutex contention). For coarse
+	// freshness checks ("is this stale by more than 5 s?") that's
+	// fine; if a future caller wants sub-second precision, document
+	// the skew or stamp both tick_started_at and tick_ended_at.
+	m_snapshot_at        = std::time(nullptr);
+}
+
+
+void CState::MarkTickFailure()
+{
+	std::unique_lock<std::shared_timed_mutex> lock(m_mu);
+	// Deliberately preserve m_snapshot_at — clients see stale
+	// `snapshot_at` next to `ec_connected=false`, so they can tell
+	// how stale the cache is. Resetting it to `now` would lie.
+	//
+	// Tick-atomicity: on failure CState may hold partial mutations
+	// from earlier in the tick. The "tick = transaction" model is
+	// atomic for events (EmitDiffsForEventBus is skipped on failure,
+	// next-tick diff is against the prior-success baseline in
+	// LastSeenState) but NOT atomic for state — no rollback. CState
+	// is a best-effort cache for /status freshness; LastSeenState
+	// is the authoritative event baseline.
+	m_ec_connected = false;
+}
+
+
+}  // namespace webapi
diff --git a/src/webapi/State.h b/src/webapi/State.h
new file mode 100644
index 0000000000..93a723cb74
--- /dev/null
+++ b/src/webapi/State.h
@@ -0,0 +1,702 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#ifndef WEBAPI_STATE_H
+#define WEBAPI_STATE_H
+
+#include <cstdint>
+#include <ctime>
+#include <functional>
+#include <map>
+#include <shared_mutex>
+#include <string>
+#include <unordered_map>
+#include <vector>
+
+
+// Cached snapshot of amuled state. One instance lives inside
+// CamuleapiApp for the whole process; the refresher (wxApp thread)
+// writes; the HTTP server (Boost.Asio thread) reads.
+//
+// **Concurrency model.** A single `std::shared_timed_mutex` guards
+// every member field. The refresher takes it exclusive once per
+// tick to swap each substruct (the swap is a `std::move`, never
+// the EC roundtrip itself). HTTP read handlers take it shared,
+// copy the relevant substruct, release, then serialise JSON
+// outside the critical section — multiple clients stack with no
+// per-handler bottleneck.
+
+namespace webapi {
+
+
+// One per file in amuled's state — keyed by ECID. Each file may
+// participate in either or both of two roles:
+//
+//   * `is_downloading` — the file is a partfile in `downloadqueue`
+//     (still acquiring chunks). Drives `/downloads`. The walker that
+//     populates this side consumes `EC_TAG_PARTFILE_*` children.
+//   * `is_shared`      — the file is uploadable: a fully-completed
+//     knownfile, OR a partfile with ≥1 chunk done (amuled flags via
+//     `EC_TAG_PARTFILE_SHARED=true`). Drives `/shared`. Populated
+//     from `EC_TAG_KNOWNFILE_*` children.
+//
+// Both flags can be true simultaneously for a partfile that's
+// currently downloading AND uploading completed chunks.
+//
+// The unified-keyed-by-ECID design mirrors amulegui's
+// `CKnownFilesRem::m_items_hash` (amule-remote-gui.cpp:1507). It
+// avoids the "shared cache has a ghost row with empty hash" bug
+// (see #201 review): on a partfile-becoming-shared tick the server's
+// CValueMap suppresses `EC_TAG_PARTFILE_HASH` because it was sent on
+// a prior partfile-walker tick, but the unified entry already has
+// hash + name from the downloads walker, so the shared walker just
+// flips `is_shared=true` and merges its own fields. No fallback.
+//
+// Role-specific state lives in sub-blocks. When a role transitions
+// true→false (partfile completes → ECID dies; or shared partfile
+// loses every chunk → `is_shared` flips off; or knownfile is un-
+// shared), the refresher resets that side's sub-block to default so
+// `/downloads` or `/shared` can never serve stale stats from a
+// previous active period.
+struct FileSnapshot {
+	// Identity / shared metadata (always populated).
+	std::uint32_t ecid       = 0;
+	std::string   hash;             // 32-char hex MD4
+	std::string   name;
+	std::string   ed2k_link;
+	std::uint64_t size       = 0;
+	std::string   priority;         // "very_low" | "low" | "normal"
+	                                // | "high"     | "release" | "auto"
+
+	bool          is_downloading = false;
+	bool          is_shared      = false;
+
+	// Download-side state — meaningful when `is_downloading` is true,
+	// reset to default on the true→false transition (and never read
+	// by `/downloads` when the flag is false).
+	struct DownloadSide {
+		std::uint64_t size_done             = 0;
+		std::uint64_t size_xfer             = 0;
+		std::uint32_t speed_bps             = 0;
+		std::string   status;          // "downloading" | "paused"
+		                                // | "completed" | "hashing" | ...
+		bool          priority_auto         = false;
+		std::uint32_t category              = 0;
+		double        percent               = 0.0;
+		std::uint32_t sources_total         = 0;
+		std::uint32_t sources_not_current   = 0;
+		std::uint32_t sources_transferring  = 0;
+		std::uint32_t sources_a4af          = 0;
+
+		// Decoded per-part state, populated by the refresher's RLE
+		// decoder pass on EC_TAG_PARTFILE_GAP_STATUS +
+		// EC_TAG_PARTFILE_PART_STATUS. Both arrays are sized to
+		// ceil(size / PARTSIZE) once a successful decode has landed;
+		// the list endpoint omits them, the detail endpoint emits
+		// `progress.parts: [{state, sources}, ...]` by walking them
+		// in parallel.
+		std::vector<std::uint64_t> decoded_gaps;
+		std::vector<std::uint16_t> decoded_part_sources;
+	} download;
+
+	// Shared-side state — meaningful when `is_shared` is true,
+	// reset on the true→false transition.
+	struct SharedSide {
+		std::uint64_t xfer_session        = 0;
+		std::uint64_t xfer_total          = 0;
+		std::uint32_t requests_session    = 0;
+		std::uint32_t requests_total      = 0;
+		std::uint32_t accepts_session     = 0;
+		std::uint32_t accepts_total       = 0;
+		std::uint32_t complete_sources    = 0;
+	} shared;
+};
+
+
+// One per peer (CUpDownClient) in the daemon's active client list.
+// Populated from the EC_TAG_CLIENT subtree inside the GET_UPDATE
+// response.
+//
+// "Client" here is amule's bidirectional peer: a remote ed2k peer
+// that's connected to us in EITHER role — uploader (we are downloading
+// from them), uploadee (we are uploading to them), queue waiter,
+// banned, etc. The cache holds ALL of them; consumer endpoints filter
+// by role:
+//  * /uploads → filter by upload_state == US_UPLOADING
+//  * /clients → no filter, full set surfaced
+// (/downloads/{hash}/sources can filter by
+// upload_file_hash matching the partfile.)
+struct ClientSnapshot {
+	std::uint32_t ecid                  = 0;
+	std::string   client_name;
+	std::string   user_hash;           // peer's user hash (32-char lowercase hex MD4)
+	std::string   ip;                  // dotted-quad
+	std::uint16_t port                 = 0;
+
+	// Software identity. EC_TAG_CLIENT_SOFTWARE ships a numeric code
+	// (SO_AMULE / SO_EMULE / etc); we decode it server-side into a
+	// short label here so consumers don't need the lookup table.
+	std::string   software;            // "amule" | "emule" | "edonkey" | "mldonkey" | ...
+	std::string   software_version;    // free-form string from EC_TAG_CLIENT_SOFT_VER_STR
+	std::string   os_info;             // free-form (CLIENT_OS_INFO)
+
+	// State machine values. We decode the raw US_*/DS_*/IS_* ints
+	// into wire strings so consumers don't reach into amule's enums.
+	std::string   upload_state;        // "uploading" | "queued" | "banned" | "connecting" | "idle" | ...
+	std::string   download_state;      // "downloading" | "onqueue" | "noneededparts" | ... | "idle"
+	std::string   ident_state;         // "unknown" | "identified" | "bad_guy" | ...
+
+	// File context — different per direction. Both correlators are
+	// 32-char lowercase MD4 hashes resolved by the refresher from
+	// EC_TAG_CLIENT_UPLOAD_FILE / EC_TAG_CLIENT_REQUEST_FILE (which
+	// amuled ships as ECIDs) against the unified m_files map. Consumers
+	// correlate against /downloads[].hash or /shared[].hash.
+	//  * upload_file_hash: partfile this peer is downloading FROM
+	//    us. Empty when not uploading to them, or when amuled's ECID
+	//    didn't resolve to a known file this tick.
+	//  * download_file_hash + download_file_name: file we are
+	//    downloading FROM this peer + the filename the peer
+	//    advertised (OP_REQFILENAMEANSWER). Empty when not in
+	//    download role.
+	std::string   upload_file_hash;     // EC_TAG_CLIENT_UPLOAD_FILE resolved
+	std::string   download_file_hash;   // EC_TAG_CLIENT_REQUEST_FILE resolved
+	std::string   download_file_name;   // EC_TAG_CLIENT_REMOTE_FILENAME
+
+	// Per-session transfer stats. CLIENT_UPLOAD_SESSION = bytes
+	// uploaded TO this peer; PARTFILE_SIZE_XFER (when re-keyed on a
+	// CLIENT_* tag) = bytes downloaded FROM this peer.
+	std::uint64_t xfer_up_session       = 0;
+	std::uint64_t xfer_down_session     = 0;
+	std::uint64_t xfer_up_total         = 0;
+	std::uint64_t xfer_down_total       = 0;
+	std::uint32_t upload_speed_bps      = 0;
+	std::uint32_t download_speed_bps    = 0;
+
+	// Upload queue position (for peers in US_ONUPLOADQUEUE).
+	// 0 when not queued.
+	std::uint32_t queue_waiting_position = 0;
+	// Remote queue rank — our position in THE PEER's upload queue
+	// (i.e. how many other ed2k clients they're going to upload to
+	// before us). 0xFFFF when their queue is full.
+	std::uint16_t remote_queue_rank      = 0;
+
+	std::uint32_t score                  = 0;   // EC_TAG_CLIENT_SCORE
+	std::string   obfuscation_status;    // "none" | "supported" | "required"
+	bool          friend_slot            = false;
+};
+
+
+// One per eD2k server in the configured server list. Identity is
+// the EC ECID (stable per amuled process lifetime). Servers are
+// fetched at full-state per refresher tick (`EC_OP_GET_SERVER_LIST`
+// has no two-phase INC equivalent — see `ExternalConn.cpp:2023`),
+// so the refresher rebuilds the whole map each cycle.
+struct ServerSnapshot {
+	std::uint32_t ecid              = 0;
+	std::string   name;
+	std::string   description;
+	std::string   version;
+	std::string   address;           // host:port form (canonical)
+	std::uint32_t ip                = 0;    // host-byte-order IPv4
+	std::uint16_t port              = 0;
+	std::uint32_t ping_ms           = 0;
+	std::uint32_t failed            = 0;
+	std::uint32_t users             = 0;
+	std::uint32_t max_users         = 0;
+	std::uint32_t files             = 0;
+	std::string   priority;          // "low" | "normal" | "high"
+	bool          is_static         = false;
+};
+
+
+// /kad endpoint. Single composite snapshot pulled from the STAT_REQ
+// response we're already fetching for /status — saves a roundtrip
+// since amuled's `EC_OP_STAT_REQ` at `EC_DETAIL_CMD` ships every
+// `EC_TAG_STATS_KAD_*` we want here.
+struct KadSnapshot {
+	std::string   state;           // "disabled" | "connecting" | "connected"
+	bool          firewalled       = false;
+	bool          firewalled_udp   = false;
+	bool          in_lan_mode      = false;
+	std::uint32_t users            = 0;
+	std::uint32_t files            = 0;
+	std::uint32_t nodes            = 0;
+	std::uint32_t indexed_sources  = 0;
+	std::uint32_t indexed_keywords = 0;
+	std::uint32_t indexed_notes    = 0;
+	std::uint32_t indexed_load     = 0;
+	std::string   ip;              // dotted-quad
+	// Buddy is the LowID-buddy state (for NAT-T peers). Most users see
+	// "no_buddy"; networks behind aggressive NAT see "connected".
+	std::string   buddy_status;    // "no_buddy" | "connecting" | "connected"
+	std::string   buddy_ip;
+	std::uint16_t buddy_port       = 0;
+};
+
+
+// One per download category (categories live in amuled's preferences;
+// the EC packet bundles them under `EC_PREFS_CATEGORIES`). Index 0
+// is the implicit "All" category. Refresher fetches the full set on
+// each tick — categories rarely change but the cost is bounded by
+// the typical 0-10 entry count.
+struct CategorySnapshot {
+	std::uint32_t index            = 0;
+	std::string   name;
+	std::string   path;
+	std::string   comment;
+	std::uint32_t color            = 0;
+	std::uint8_t  priority_code    = 0;
+	std::string   priority;        // human-readable (very_low/low/normal/high/release/auto)
+};
+
+
+// One node in the recursive stats tree (amuled's "Statistics" panel
+// contents — counters, ratios, uptime, transfer aggregates, etc.).
+// amule emits a flat-label representation: `GetDisplayString()`
+// returns the rendered text (e.g. "Total bytes transferred: 12.3 GiB")
+// rather than a typed value, so we pass it through as a single
+// human-readable string and let clients render the tree verbatim.
+struct StatsTreeNode {
+	std::string label;
+	std::vector<StatsTreeNode> children;
+};
+
+
+// Time-series data for /stats/graphs/{graph}. amuled keeps a
+// circular buffer of uint32 samples per series at 1-sec cadence;
+// the refresher pulls the most recent `kRefreshWindow` samples per
+// tick and stores them here, with the most recent sample at
+// `points.back()` corresponding to the snapshot wall-clock at
+// `snapshot_at` (CState::SnapshotAt()).
+//
+// Four series fan out from a single `EC_OP_GET_STATSGRAPHS` packet
+// (download, upload, connections, kad). Handler picks the one named
+// in the `{graph}` path segment.
+struct StatsGraphs {
+	// Sample cadence in seconds. amuled's CStatsCollection uses 1s.
+	// Used as the `interval` field in the response.
+	std::uint32_t interval_seconds = 1;
+
+	std::vector<std::uint32_t> download_bps;
+	std::vector<std::uint32_t> upload_bps;
+	std::vector<std::uint32_t> connections;
+	std::vector<std::uint32_t> kad_nodes;
+
+	// Session running totals — single uint64 per series, reported
+	// alongside the time-series so the panel can show "this session
+	// total" without needing a separate roundtrip.
+	std::uint64_t session_download_bytes = 0;
+	std::uint64_t session_upload_bytes   = 0;
+	std::uint64_t session_kad_bytes      = 0;
+};
+
+
+// One result from a /search/results poll. Identity is the file's
+// MD4 hash. amuled accumulates results in its `searchlist`
+// singleton as packets come in from servers/Kad; the client polls
+// EC_OP_SEARCH_RESULTS to drain.
+struct SearchResult {
+	std::uint32_t ecid                  = 0;
+	std::string   hash;             // 32-char hex MD4
+	std::string   name;
+	std::uint64_t size                  = 0;
+	std::uint32_t source_count          = 0;
+	std::uint32_t complete_source_count = 0;
+	bool          already_have          = false;
+	std::uint8_t  rating                = 0;
+};
+
+
+// Refresher-tracked lifecycle of the currently-active (or last-finished)
+// search. The refresher reads EC_TAG_SEARCH_LIFECYCLE_STATE (added in the
+// EC protocol cleanup landed earlier in this PR) and maps it directly
+// here — no sentinel decode, no state machine, no defensive timeout.
+struct SearchProgressSnapshot {
+	// True between POST /search and the daemon-reported finished state.
+	// Drives whether the refresher keeps polling EC_OP_SEARCH_RESULTS +
+	// EC_OP_SEARCH_PROGRESS.
+	bool          active   = false;
+	// "global" | "local" | "kad". Captured from POST /search's `type`
+	// param. Surfaced in `search_progress` SSE so consumers can
+	// distinguish which network produced the result set.
+	std::string   kind;
+	std::uint32_t percent  = 0;     // 0..100, daemon-computed for every
+	                                // kind (global = real server-queue
+	                                // percent; Kad = cosmetic time-ramp;
+	                                // 100 on finished)
+	bool          complete = false; // true exactly once on the lifecycle
+	                                // RUNNING → FINISHED edge
+};
+
+
+// `m_amule_log_lines` in CState caches /logs/amule. amule's EC
+// server piggybacks new lines on STAT_REQ at `EC_DETAIL_FULL` (see
+// `AddLoggerTag` in ExternalConn.cpp:700-715) via a per-EC-connection
+// cursor (CLoggerAccess) — each call returns ONLY lines emitted
+// since the previous STAT_REQ from the same connection. Clients
+// tail with `?tail=N`.
+//
+// **No cap on history.** Per operator preference, every line stays
+// in memory until amuleapi restarts; log volume is bounded by
+// operator habits (idle ~tens of KB/day; busy ~hundreds).
+
+
+// /logs/serverinfo. amule has no incremental EC op for this log
+// (no equivalent of CLoggerAccess for ServerInfoLog), so the
+// refresher fetches the entire string via EC_OP_GET_SERVERINFO each
+// tick and the cache stores the latest snapshot. Server-info logs
+// are small (a few KB at most — just server connection chatter), so
+// the per-tick rebuild cost is negligible.
+struct ServerInfoLog {
+	std::string text;
+};
+
+
+// amuled preferences subset surfaced via /preferences. The amuled
+// preferences corpus is enormous (every UI panel has its own
+// section); for v0.1 we ship the common-case fields:
+// nick, transfer limits, ports, connection toggles. / later
+// can extend this if a real client reports needing more.
+struct PreferencesSnapshot {
+	// [General]
+	std::string   nickname;
+	std::string   user_hash;
+	std::string   host_name;
+	bool          check_new_version = false;
+
+	// [Connection]
+	std::uint32_t max_upload_kbps        = 0;
+	std::uint32_t max_download_kbps      = 0;
+	std::uint32_t max_upload_cap_kbps    = 0;
+	std::uint32_t max_download_cap_kbps  = 0;
+	std::uint32_t slot_allocation        = 0;
+	std::uint16_t tcp_port               = 0;
+	std::uint16_t udp_port               = 0;
+	bool          udp_disabled           = false;
+	std::uint32_t max_sources_per_file   = 0;
+	std::uint32_t max_connections        = 0;
+	bool          autoconnect            = false;
+	bool          reconnect              = false;
+	bool          network_ed2k           = false;
+	bool          network_kad            = false;
+};
+
+
+struct StatusSnapshot {
+	// "connected" / "connecting" / "disconnected" — the literal
+	// string the API returns. Done at parse time rather than
+	// emit time so the snapshot is self-describing (debug-dump-
+	// friendly) and the emit path stays one-liner trivial.
+	std::string ed2k_state    = "disconnected";
+	std::string kad_state     = "disabled";
+
+	// Nickname is intentionally NOT a /status field — it lives in the
+	// preferences EC namespace, not the STAT_REQ response. amuleapi
+	// surfaces it via /api/v0/preferences where it belongs
+	// semantically (it's a user-edited value, not a connection-state
+	// observation). Same call /status that PHP's am_status template
+	// makes.
+
+	// Server the daemon is currently connected to (eD2k only — Kad
+	// has no equivalent). Empty when ed2k_state != "connected".
+	std::string server_name;
+	std::string server_ip;
+	std::uint32_t server_port = 0;
+
+	// True when the daemon is connected to ed2k but in LowID mode
+	// (NAT'd, can't accept incoming). adds NAT-T affordances
+	// that change this calculus; until then the field maps 1:1 to the
+	// EC CONNSTATE bit.
+	bool        ed2k_lowid    = false;
+	// True when Kad is running but firewalled.
+	bool        kad_firewalled = false;
+
+	// Bytes per second (NOT kB) so the field name matches the wire
+	// units throughout. Clients that want kB/s do the divide.
+	std::uint64_t download_bps = 0;
+	std::uint64_t upload_bps   = 0;
+
+	// Aggregate counts pulled by the same EC_OP_STATS round-trip.
+	std::uint32_t ul_queue_len     = 0;
+	std::uint32_t total_src_count  = 0;
+};
+
+
+// ECID-keyed file map + hash→ECID index in lockstep. The index is
+// maintained inline on every emplace/erase so the obvious lookup
+// directions both stay O(1) avg without a per-tick rebuild pass:
+//  * ECID → entry via std::unordered_map::find (file_map[]).
+//  * 32-char hex MD4 hash → ECID via FindEcidByHash (index[]).
+//
+// Walkers reach in via find()/emplace()/erase()/begin()/end() — the
+// same surface they had when this was a raw std::map<uint32_t,
+// FileSnapshot>&. The wrapper intercepts the two mutations that move
+// hashes around and keeps the index consistent.
+//
+// Invariant: a FileSnapshot's `hash` is content-derived and never
+// changes once set. Walkers MUST NOT reassign `hash` via the iterator
+// (the index would desync). Set hash before emplace, never after.
+class FileMap {
+public:
+	using map_type       = std::unordered_map<std::uint32_t, FileSnapshot>;
+	using iterator       = map_type::iterator;
+	using const_iterator = map_type::const_iterator;
+
+	iterator       find(std::uint32_t ecid)       { return m_files.find(ecid); }
+	const_iterator find(std::uint32_t ecid) const { return m_files.find(ecid); }
+	iterator       begin()       { return m_files.begin(); }
+	const_iterator begin() const { return m_files.begin(); }
+	iterator       end()         { return m_files.end(); }
+	const_iterator end()   const { return m_files.end(); }
+	std::size_t    size()  const { return m_files.size(); }
+	bool           empty() const { return m_files.empty(); }
+
+	// By-value param so callers can pass either an lvalue (copies) or
+	// rvalue (moves) with the same call site — std::unordered_map's
+	// variadic emplace is too liberal for our index-keeping discipline.
+	std::pair<iterator, bool> emplace(std::uint32_t ecid, FileSnapshot f)
+	{
+		auto r = m_files.emplace(ecid, std::move(f));
+		if (r.second && !r.first->second.hash.empty()) {
+			m_hash_to_ecid[r.first->second.hash] = ecid;
+		}
+		return r;
+	}
+
+	iterator erase(iterator it)
+	{
+		if (!it->second.hash.empty()) {
+			auto hit = m_hash_to_ecid.find(it->second.hash);
+			// Defence: only clear the index slot if it still points at
+			// this ECID. A later emplace with the same hash but a
+			// different ECID could have rewired the slot already.
+			if (hit != m_hash_to_ecid.end() && hit->second == it->first) {
+				m_hash_to_ecid.erase(hit);
+			}
+		}
+		return m_files.erase(it);
+	}
+
+	void clear()
+	{
+		m_files.clear();
+		m_hash_to_ecid.clear();
+	}
+
+	bool FindEcidByHash(const std::string &hash, std::uint32_t &out) const
+	{
+		auto it = m_hash_to_ecid.find(hash);
+		if (it == m_hash_to_ecid.end()) return false;
+		out = it->second;
+		return true;
+	}
+
+private:
+	map_type                                       m_files;
+	std::unordered_map<std::string, std::uint32_t> m_hash_to_ecid;
+};
+
+
+// One State instance per amuleapi process. The mutex protects every
+// member field; refresh swaps the whole struct under it, handlers
+// read the substructs they need under it.
+class CState {
+public:
+	// True once the refresher has completed at least one successful
+	// tick. Until then, the /status endpoint returns 503 with
+	// `ec_unavailable` so clients can tell "amuleapi is up but amuled
+	// isn't responding" apart from a hard 5xx.
+	bool             HasFirstSnapshot() const;
+
+	// Wall-clock at which the last successful tick completed. Used
+	// to populate `snapshot_at` / `snapshot_at_unix` on every list
+	// response.
+	std::time_t      SnapshotAt() const;
+
+	// True iff the most recent tick succeeded. False after a tick
+	// failed (EC timeout / disconnect); the refresher keeps the
+	// stale snapshot for clients but flips this flag.
+	bool             EcConnected() const;
+
+	StatusSnapshot                  Status()      const;
+	KadSnapshot                     Kad()         const;
+	// One-shot snapshot of the four scalars /api/v0/status composes
+	// from. Taken under a single shared_lock so the four pieces
+	// describe the same refresher tick — no risk of `status` and
+	// `kad` straddling a tick boundary.
+	struct DashboardSnapshot {
+		StatusSnapshot status;
+		KadSnapshot    kad;
+		std::time_t    snapshot_at = 0;
+		bool           ec_connected = false;
+	};
+	DashboardSnapshot               Dashboard()   const;
+	PreferencesSnapshot             Preferences() const;
+	// Full snapshot of the amule log lines (oldest-first). API
+	// handlers slice the tail before serialising via the
+	// `?tail=N` query param.
+	std::vector<std::string>        AmuleLog()    const;
+	ServerInfoLog                   ServerInfo()  const;
+
+	// Flat list views. Reads the ECID-keyed map under shared_lock and
+	// returns a copy of the snapshot values in unordered_map iteration
+	// order — bucket-dependent, NOT stable across ticks. Consumers
+	// that want a specific order sort on their side (by name / date /
+	// progress / etc.).
+	//
+	// `Downloads()` filters `m_files` by `is_downloading`, `Shared()`
+	// filters by `is_shared`. Both views consult the same underlying
+	// unified map — see FileSnapshot above for the role-flag model.
+	std::vector<FileSnapshot>     Downloads() const;
+	std::vector<FileSnapshot>     Shared()    const;
+	// Unfiltered view used by EventDiff to compute role-flag
+	// transitions. Not surfaced on the REST API.
+	std::vector<FileSnapshot>     Files()     const;
+
+	// Full peer list (all upload_state values, including queue
+	// waiters, idle peers, and banned). Backs /clients.
+	// The legacy /uploads endpoint is retired — consumers query
+	// /clients and filter by role on their side.
+	std::vector<ClientSnapshot>   Clients()   const;
+
+	std::vector<ServerSnapshot>   Servers()   const;
+	std::vector<SearchResult>     Search()    const;
+	SearchProgressSnapshot        SearchProgress() const;
+
+	// Categories aren't ECID-keyed (they come in via the
+	// preferences packet as an indexed array); keep them as a plain
+	// vector copied out under the shared lock.
+	std::vector<CategorySnapshot> Categories() const;
+
+	// /stats/tree returns the recursive tree as a single bare object.
+	StatsTreeNode                 StatsTree()  const;
+	// /stats/graphs/{graph} reads one series out of the bundle.
+	StatsGraphs                   Graphs()     const;
+
+	// Look up a single file by 32-char hex hash, then check the role.
+	// Returns true on hit + role match, false on miss; on miss `out`
+	// is left untouched. Used by /downloads/{hash} (download role) and
+	// /shared/{hash} (shared role) — both inspect the same m_files map.
+	bool             FindDownload(const std::string &hash_hex,
+	                              FileSnapshot &out) const;
+	bool             FindShared  (const std::string &hash_hex,
+	                              FileSnapshot &out) const;
+
+	// ECID-keyed counterparts. Used internally — there is no
+	// /downloads/{ecid} or /shared/{ecid} path; the wire surface is
+	// hash-only. CClientList::ApplyGetUpdate also reaches in here when
+	// resolving EC_TAG_CLIENT_UPLOAD_FILE.
+	bool             FindDownloadByEcid(std::uint32_t ecid,
+	                                    FileSnapshot &out) const;
+	bool             FindSharedByEcid (std::uint32_t ecid,
+	                                    FileSnapshot &out) const;
+
+	// INC-mode delta application. The refresher takes the unique_lock
+	// once per EC roundtrip, then calls a callback with a mutable
+	// reference to the unified ECID-keyed map; the callback walks the
+	// EC response and upserts/removes individual entries plus role
+	// flags. One unique acquisition per tick rather than N — reader
+	// latency stays bounded by the parse loop, not by N independent
+	// acquisitions. Both MutateDownloads and MutateShared operate on
+	// the SAME m_files map; the callback decides which role to flip.
+	// MutateDownloads/Shared hand out the FileMap wrapper, which keeps
+	// its internal hash→ECID index in sync on every emplace/erase.
+	void             MutateDownloads(const std::function<void(FileMap &)> &fn);
+	void             MutateShared   (const std::function<void(FileMap &)> &fn);
+	void             MutateClients  (const std::function<
+	                  void(std::map<std::uint32_t, ClientSnapshot>   &)> &fn);
+	void             MutateServers  (const std::function<
+	                  void(std::map<std::uint32_t, ServerSnapshot>   &)> &fn);
+	void             MutateSearch   (const std::function<
+	                  void(std::map<std::uint32_t, SearchResult>     &)> &fn);
+
+	// Wholesale reset paths. Called by the refresher after a
+	// MarkTickFailure → MarkTickSuccess transition (the server's
+	// CValueMap was reset on reconnect; stale entries that vanished
+	// during the disconnect window would otherwise live forever in
+	// the cache).
+	void             ResetLists();
+
+	// Refresher-side write paths.
+	void             WriteStatus(StatusSnapshot s);
+	void             WriteKad(KadSnapshot k);
+	void             WritePreferences(PreferencesSnapshot p);
+	void             WriteCategories(std::vector<CategorySnapshot> c);
+	// Append one or more new amule-log lines to the ring; trims oldest
+	// entries when capacity is exceeded. Called once per refresher
+	// tick with the lines drained from EC_TAG_STATS_LOGGER_MESSAGE.
+	void             AppendAmuleLog(std::vector<std::string> new_lines);
+	// Drop every cached amule-log line. Called by DELETE /logs/amule
+	// after the EC_OP_RESET_LOG roundtrip — the refresher only appends
+	// (it has no equivalent of "shrink to amuled's current count"), so
+	// the in-process cache MUST be cleared explicitly or the next GET
+	// will keep returning the pre-reset lines. The next refresher tick
+	// resumes appending from amuled's now-empty buffer.
+	void             ClearAmuleLog();
+	void             WriteServerInfo(ServerInfoLog s);
+	// Called by POST /search. Wipes m_search, sets m_search_progress
+	// to active=true with the requested `kind`. The refresher takes
+	// over from there, mapping EC_TAG_SEARCH_LIFECYCLE_STATE into
+	// `complete` / `active` on each tick.
+	void             MarkSearchStarted(const std::string &kind);
+	// Refresher-side write path for the search progress snapshot.
+	void             WriteSearchProgress(SearchProgressSnapshot s);
+	void             WriteStatsTree(StatsTreeNode t);
+	void             WriteGraphs(StatsGraphs g);
+	void             MarkTickSuccess();
+	void             MarkTickFailure();
+
+private:
+	mutable std::shared_timed_mutex m_mu;
+
+	bool             m_has_first_snapshot = false;
+	bool             m_ec_connected       = false;
+	std::time_t      m_snapshot_at        = 0;
+
+	StatusSnapshot                                  m_status;
+	KadSnapshot                                     m_kad;
+	PreferencesSnapshot                             m_preferences;
+	std::vector<CategorySnapshot>                   m_categories;
+	// Unified ECID-keyed file map. A single entry may participate in
+	// the /downloads view (`is_downloading`), the /shared view
+	// (`is_shared`), or both. See FileSnapshot's header comment for
+	// why the two views share storage. FileMap also owns a hash→ECID
+	// index, maintained inline on every emplace/erase so /downloads/{hash}
+	// + /shared/{hash} lookups stay O(1) avg without a per-tick rebuild.
+	FileMap                                         m_files;
+
+	std::map<std::uint32_t, ClientSnapshot>         m_clients;
+	std::map<std::uint32_t, ServerSnapshot>         m_servers;
+	std::vector<std::string>                        m_amule_log_lines;
+	ServerInfoLog                                   m_server_info;
+	StatsTreeNode                                   m_stats_tree;
+	StatsGraphs                                     m_graphs;
+	std::map<std::uint32_t, SearchResult>           m_search;
+	SearchProgressSnapshot                          m_search_progress;
+};
+
+
+}  // namespace webapi
+
+#endif // WEBAPI_STATE_H
diff --git a/src/webapi/StaticFs.cpp b/src/webapi/StaticFs.cpp
new file mode 100644
index 0000000000..ca9c4417ec
--- /dev/null
+++ b/src/webapi/StaticFs.cpp
@@ -0,0 +1,75 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+
+#include "StaticFs.h"
+
+#include <cstdlib>
+#include <cstring>
+#include <limits.h>
+#include <sys/stat.h>
+
+namespace webapi {
+
+bool IsDir(const std::string &path)
+{
+	if (path.empty()) return false;
+	// Windows MSVCRT stat() rejects a trailing slash on a directory
+	// path; POSIX accepts it. Trim consistently.
+	std::string p = path;
+	while (p.size() > 1
+	       && (p.back() == '/' || p.back() == '\\')) {
+		p.pop_back();
+	}
+	struct stat st{};
+	if (::stat(p.c_str(), &st) != 0) return false;
+	return S_ISDIR(st.st_mode);
+}
+
+
+bool ResolveWithinRoot(const std::string &root, const std::string &rel,
+                       std::string &fs_out)
+{
+	char root_real[PATH_MAX];
+	char fs_real[PATH_MAX];
+#ifdef _WIN32
+	// _fullpath() is lexical-only (no reparse-point resolution). On
+	// Windows the symlink containment threat model is weaker — symlinks
+	// require elevation and are functionally exotic, so lexical
+	// containment is sufficient for the operator-misconfig case the
+	// rejection step targets.
+	if (!_fullpath(root_real, root.c_str(), PATH_MAX)) return false;
+	const std::string joined = std::string(root_real) + "\\" + rel;
+	if (!_fullpath(fs_real, joined.c_str(), PATH_MAX)) return false;
+	struct stat st;
+	if (::stat(fs_real, &st) != 0) return false;
+#else
+	if (!realpath(root.c_str(), root_real)) return false;
+	const std::string joined = std::string(root_real) + "/" + rel;
+	if (!realpath(joined.c_str(), fs_real)) return false;
+#endif
+	// _fullpath() on Windows preserves a trailing path separator from
+	// its input, which then breaks the prefix comparison below. POSIX
+	// realpath() strips them. Normalise here so the containment check
+	// is platform-agnostic.
+	std::size_t root_len = std::strlen(root_real);
+	while (root_len > 1
+	       && (root_real[root_len - 1] == '/'
+	        || root_real[root_len - 1] == '\\')) {
+		root_real[--root_len] = '\0';
+	}
+	if (std::strncmp(fs_real, root_real, root_len) != 0) return false;
+	const char sep = fs_real[root_len];
+	if (sep != '/' && sep != '\\' && sep != '\0') return false;
+	fs_out.assign(fs_real);
+	return true;
+}
+
+}  // namespace webapi
diff --git a/src/webapi/StaticFs.h b/src/webapi/StaticFs.h
new file mode 100644
index 0000000000..5501d3abc5
--- /dev/null
+++ b/src/webapi/StaticFs.h
@@ -0,0 +1,38 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+
+// Small filesystem helpers shared between ServeStaticFile (Api.cpp) and
+// its security-critical unit tests (StaticFsTest). Lifted to its own
+// TU so the test target can link the helper without dragging the rest
+// of the dispatcher (and its wx/Boost.Beast/EC web).
+
+#ifndef AMULE_WEBAPI_STATICFS_H
+#define AMULE_WEBAPI_STATICFS_H
+
+#include <string>
+
+namespace webapi {
+
+bool IsDir(const std::string &path);
+
+// Resolve `rel` under `root` and reject if the result escapes `root`
+// (symlink containment + belt-and-suspenders against any traversal
+// that slips past the upstream path-pattern filter). Writes the
+// canonical absolute path into `fs_out` on success. Any failure
+// (missing file, escape, OS error) returns false — the caller emits
+// an opaque 404 either way to keep the directory layout non-
+// enumerable from outside.
+bool ResolveWithinRoot(const std::string &root, const std::string &rel,
+                       std::string &fs_out);
+
+}  // namespace webapi
+
+#endif  // AMULE_WEBAPI_STATICFS_H
diff --git a/src/webapi/TtlCache.h b/src/webapi/TtlCache.h
new file mode 100644
index 0000000000..8d9c800e81
--- /dev/null
+++ b/src/webapi/TtlCache.h
@@ -0,0 +1,147 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#ifndef WEBAPI_TTL_CACHE_H
+#define WEBAPI_TTL_CACHE_H
+
+#include <chrono>
+#include <condition_variable>
+#include <mutex>
+#include <utility>
+
+
+namespace webapi {
+
+
+// Single-flight TTL cache for lazy-fetched endpoints
+// (/logs/serverinfo, /stats/tree, /stats/graphs/{graph},
+// /search/results). HTTP handlers drive their own EC fetches on
+// demand, coalescing burst reads via a 1 s TTL.
+//
+// **Single-flight semantics.** Only one thread runs `fetch()` for a
+// given stale-or-unset cache; concurrent callers park on a condvar
+// while the inflight thread runs the EC roundtrip with the cache
+// mutex DROPPED. Once the result is stored and the flag clears,
+// every waiter observes the just-stored value and returns it without
+// re-fetching.
+//
+// **Why drop the mutex around fetch?** A 30 s amuled stall on
+// /stats/tree would otherwise park every concurrent reader of that
+// endpoint for the stall's duration. Dropping the cache mutex around
+// the EC call lets concurrent readers cooperate on the single
+// inflight fetch without serialising on the slowest amuled response.
+//
+// **Lock ordering.** The fetcher lambda acquires `m_ec_mtx` while
+// this cache's `m_mu` is NOT held. Still single-flight per endpoint
+// because `m_inflight` gates concurrent fetches.
+//
+// The cached `T` must be copyable (returned by value so `m_mu` isn't
+// held across JSON serialisation).
+template <class T>
+class CTtlCache {
+public:
+	using clock_t = std::chrono::steady_clock;
+
+	// Returns a copy of the freshest value. If the cache is fresh,
+	// returns immediately under a brief lock. If stale-or-unset:
+	// one caller becomes the "inflight" worker (drops the lock,
+	// runs fetch, re-takes the lock, stores, broadcasts);
+	// concurrent callers wait on the condvar until inflight clears
+	// and then read the stored value.
+	template <class Fetcher>
+	T GetOrFetch(std::chrono::milliseconds ttl, Fetcher fetch)
+	{
+		std::unique_lock<std::mutex> lk(m_mu);
+		while (true) {
+			const auto now = clock_t::now();
+			const bool unset = (m_fetched_at == clock_t::time_point{});
+			if (!unset && (now - m_fetched_at) <= ttl) {
+				return m_value;
+			}
+			if (m_inflight) {
+				// Another caller is doing the EC roundtrip. Wait
+				// for them to finish, then re-check freshness in
+				// case yet another fetch is needed (e.g. the
+				// inflight result raced our TTL clamp because
+				// fetch was slow).
+				m_cv.wait(lk, [this]{ return !m_inflight; });
+				continue;
+			}
+			// We're the inflight worker. Claim the slot, drop the
+			// lock, do the fetch unguarded so peers can park on
+			// the condvar without our long EC call serialising
+			// them on the cache mutex.
+			m_inflight = true;
+			lk.unlock();
+			T fetched;
+			try {
+				fetched = fetch();
+			} catch (...) {
+				// Clear inflight + wake waiters even on exception
+				// so we don't park them forever.
+				{
+					std::lock_guard<std::mutex> g(m_mu);
+					m_inflight = false;
+				}
+				m_cv.notify_all();
+				throw;
+			}
+			{
+				std::lock_guard<std::mutex> g(m_mu);
+				m_value      = std::move(fetched);
+				m_fetched_at = clock_t::now();
+				m_inflight   = false;
+			}
+			m_cv.notify_all();
+			// Re-acquire to read the value under the lock so
+			// the contract (returned T is a stable copy of the
+			// just-stored snapshot) holds in the face of a racing
+			// Invalidate.
+			std::lock_guard<std::mutex> g(m_mu);
+			return m_value;
+		}
+	}
+
+	// Invalidate. Future GetOrFetch will trigger a fresh fetch
+	// regardless of TTL. Used by mutations that touch an
+	// endpoint's data (e.g. POST /search invalidating
+	// /search/results).
+	void Invalidate()
+	{
+		std::lock_guard<std::mutex> g(m_mu);
+		m_fetched_at = clock_t::time_point{};
+	}
+
+private:
+	mutable std::mutex      m_mu;
+	std::condition_variable m_cv;
+	clock_t::time_point     m_fetched_at{};
+	T                       m_value{};
+	bool                    m_inflight = false;
+};
+
+
+}  // namespace webapi
+
+#endif // WEBAPI_TTL_CACHE_H
diff --git a/src/webapi/static/index.html b/src/webapi/static/index.html
new file mode 100644
index 0000000000..307c9fffd9
--- /dev/null
+++ b/src/webapi/static/index.html
@@ -0,0 +1,25 @@
+<!doctype html>
+<html lang="en">
+<head>
+	<meta charset="utf-8">
+	<meta name="viewport" content="width=device-width, initial-scale=1">
+	<title>amuleapi is running</title>
+	<style>
+		html, body { margin: 0; padding: 0; height: 100%; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; background: #1a1a1a; color: #d0d0d0; }
+		body { display: flex; align-items: center; justify-content: center; }
+		.wrap { text-align: center; max-width: 32em; padding: 2em; }
+		h1 { font-size: 1.6em; margin: 0 0 .4em; color: #f0f0f0; }
+		p { margin: .8em 0; line-height: 1.4; }
+		code { background: #2a2a2a; padding: .15em .35em; border-radius: 3px; font-size: 0.95em; }
+		a { color: #8ab4f8; }
+	</style>
+</head>
+<body>
+	<div class="wrap">
+		<h1>amuleapi is running</h1>
+		<p>The daemon is up and the REST surface is being served under <code>/api/v0/</code>.</p>
+		<p>No frontend bundle is wired up at this <code>StaticRoot</code> yet; this placeholder confirms static serving works end-to-end. Point <code>StaticRoot</code> in your <code>amuleapi.conf</code> at a real frontend directory to replace this page.</p>
+		<p>See <a href="https://github.com/amule-org/amule">amule-org/amule</a> for the API reference.</p>
+	</div>
+</body>
+</html>
diff --git a/unittests/curl-tests/amuleapi/01-version-and-errors.sh b/unittests/curl-tests/amuleapi/01-version-and-errors.sh
new file mode 100755
index 0000000000..fde6f67c00
--- /dev/null
+++ b/unittests/curl-tests/amuleapi/01-version-and-errors.sh
@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+#
+# amuleapi 01-version-and-errors — daemon skeleton smoke. Asserts the single
+# `/api/v0/version` endpoint and the error-shape envelope.
+#
+# Usage:
+#   amuleapi --config-dir=/tmp/amuleapi-test &
+#   ./01-version-and-errors.sh
+#
+# Environment:
+#   HOST=localhost:4713   amuleapi endpoint (default port)
+#
+# Exits 0 on success, 1 on any failed assertion, 2 on bring-up error.
+
+set -u
+set -o pipefail
+
+HOST=${HOST:-localhost:4713}
+
+FAIL_COUNT=0
+TEST_COUNT=0
+
+CURL_BODY_FILE=$(mktemp -t amuleapi_01_version_and_errors_body.XXXXXX)
+trap 'rm -f "$CURL_BODY_FILE"' EXIT
+
+_die()  { echo "FATAL: $*" >&2; exit 2; }
+_pass() { TEST_COUNT=$((TEST_COUNT+1)); echo "  PASS  $1"; }
+_fail() {
+	TEST_COUNT=$((TEST_COUNT+1)); FAIL_COUNT=$((FAIL_COUNT+1))
+	echo "  FAIL  $1"
+	shift
+	for arg in "$@"; do echo "        $arg"; done
+}
+
+_curl() {
+	local resp
+	resp=$(curl -s --max-time 10 \
+		-o "$CURL_BODY_FILE" -w '%{http_code}' "$@") \
+		|| _die "curl invocation failed for $*"
+	CURL_STATUS=$resp
+	CURL_BODY=$(cat "$CURL_BODY_FILE")
+}
+
+_assert_status() {
+	local expected=$1 label=$2
+	if [ "$CURL_STATUS" = "$expected" ]; then
+		_pass "$label (HTTP $CURL_STATUS)"
+	else
+		_fail "$label" "expected HTTP $expected, got $CURL_STATUS" \
+			"body head: $(printf '%s' "$CURL_BODY" | head -c 200)"
+	fi
+}
+
+_assert_json_eq() {
+	local expr=$1 expected=$2 label=$3
+	local actual
+	actual=$(printf '%s' "$CURL_BODY" | jq -r "$expr" 2>/dev/null) \
+		|| _fail "$label" "body was not valid JSON" "body: $CURL_BODY"
+	if [ "$actual" = "$expected" ]; then
+		_pass "$label"
+	else
+		_fail "$label" "expected $expected, got $actual" "body: $CURL_BODY"
+	fi
+}
+
+if ! command -v jq >/dev/null 2>&1; then
+	_die "jq is required for JSON assertions. brew install jq."
+fi
+if ! curl -s -o /dev/null --max-time 2 "$HOST/" 2>/dev/null; then
+	_die "amuleapi at $HOST is not reachable. Start amuleapi first."
+fi
+
+echo "amuleapi 01-version-and-errors smoke @ $HOST"
+
+# 1. GET /api/v0/version → 200 + JSON with name=amuleapi, api_version=v0.
+_curl "$HOST/api/v0/version"
+_assert_status 200 "GET /api/v0/version returns 200"
+_assert_json_eq '.name'        amuleapi '/api/v0/version reports name=amuleapi'
+_assert_json_eq '.api_version' v0       '/api/v0/version reports api_version=v0'
+
+# 2. amule_version field — non-empty. On release builds it's
+#    e.g. "3.0.1"; on the `master` line it's the literal "GIT"
+#    (PACKAGE_VERSION default in the top-level CMakeLists.txt).
+#    Pinning a shape would force the smoke to know which kind of
+#    build it's poking at, so just assert the field is populated.
+_assert_json_eq '.amule_version | length > 0' \
+	true '/api/v0/version reports a non-empty amule_version'
+
+# 3. Method other than GET/HEAD → 405 with the canonical error envelope.
+_curl -X DELETE "$HOST/api/v0/version"
+_assert_status 405 "DELETE /api/v0/version yields 405"
+_assert_json_eq '.error.code' method_not_allowed \
+	'/api/v0/version 405 carries error.code=method_not_allowed'
+
+# 4. Unknown route → 404 with the canonical error envelope.
+_curl "$HOST/api/v0/does-not-exist"
+_assert_status 404 "GET /api/v0/does-not-exist yields 404"
+_assert_json_eq '.error.code' not_found \
+	'404 carries error.code=not_found'
+
+# 5. HEAD /api/v0/version — same status code as GET, no body required.
+_curl -I "$HOST/api/v0/version"
+_assert_status 200 "HEAD /api/v0/version returns 200"
+
+# Summary.
+echo
+if [ "$FAIL_COUNT" -eq 0 ]; then
+	echo "OK: $TEST_COUNT/$TEST_COUNT passed"
+	exit 0
+fi
+echo "FAIL: $FAIL_COUNT/$TEST_COUNT failed"
+exit 1
diff --git a/unittests/curl-tests/amuleapi/02-auth.sh b/unittests/curl-tests/amuleapi/02-auth.sh
new file mode 100755
index 0000000000..9588c4d15f
--- /dev/null
+++ b/unittests/curl-tests/amuleapi/02-auth.sh
@@ -0,0 +1,230 @@
+#!/usr/bin/env bash
+#
+# amuleapi 02-auth — auth surface. Exercises /api/v0/auth/login,
+# /auth/session, /auth/logout against a freshly-started amuleapi
+# whose admin password is `adminpass` and whose guest password is
+# unset.
+#
+# Bring-up convention (matches the README in the parent dir):
+#   rm -rf /tmp/amuleapi-02-auth && mkdir -p /tmp/amuleapi-02-auth
+#   amuleapi --config-dir=/tmp/amuleapi-02-auth --host=127.0.0.1 \
+#            --port=4712 --password=amule --set-admin-pass=adminpass
+#   amuleapi --config-dir=/tmp/amuleapi-02-auth --host=127.0.0.1 \
+#            --port=4712 --password=amule &
+#   ./02-auth.sh
+#
+# Environment:
+#   HOST=localhost:4713         amuleapi endpoint
+#   ADMIN_PASS=adminpass        plaintext admin password
+#
+# Exits 0 on success, 1 on any failed assertion, 2 on bring-up error.
+
+set -u
+set -o pipefail
+
+HOST=${HOST:-localhost:4713}
+ADMIN_PASS=${ADMIN_PASS:-adminpass}
+
+FAIL_COUNT=0
+TEST_COUNT=0
+
+CURL_BODY_FILE=$(mktemp -t amuleapi_02_auth_body.XXXXXX)
+CURL_HDR_FILE=$(mktemp -t amuleapi_02_auth_hdr.XXXXXX)
+COOKIE_JAR=$(mktemp -t amuleapi_02_auth_cookies.XXXXXX)
+trap 'rm -f "$CURL_BODY_FILE" "$CURL_HDR_FILE" "$COOKIE_JAR"' EXIT
+
+_die()  { echo "FATAL: $*" >&2; exit 2; }
+_pass() { TEST_COUNT=$((TEST_COUNT+1)); echo "  PASS  $1"; }
+_fail() {
+	TEST_COUNT=$((TEST_COUNT+1)); FAIL_COUNT=$((FAIL_COUNT+1))
+	echo "  FAIL  $1"
+	shift
+	for arg in "$@"; do echo "        $arg"; done
+}
+
+_curl() {
+	local resp
+	resp=$(curl -s --max-time 10 \
+		-D "$CURL_HDR_FILE" \
+		-o "$CURL_BODY_FILE" -w '%{http_code}' "$@") \
+		|| _die "curl invocation failed for $*"
+	CURL_STATUS=$resp
+	CURL_BODY=$(cat "$CURL_BODY_FILE")
+	CURL_HDR=$(cat "$CURL_HDR_FILE")
+}
+
+_assert_status() {
+	local expected=$1 label=$2
+	if [ "$CURL_STATUS" = "$expected" ]; then
+		_pass "$label (HTTP $CURL_STATUS)"
+	else
+		_fail "$label" "expected HTTP $expected, got $CURL_STATUS" \
+			"body head: $(printf '%s' "$CURL_BODY" | head -c 200)"
+	fi
+}
+
+_assert_json_eq() {
+	local expr=$1 expected=$2 label=$3
+	local actual
+	actual=$(printf '%s' "$CURL_BODY" | jq -r "$expr" 2>/dev/null) \
+		|| _fail "$label" "body was not valid JSON" "body: $CURL_BODY"
+	if [ "$actual" = "$expected" ]; then
+		_pass "$label"
+	else
+		_fail "$label" "expected $expected, got $actual" "body: $CURL_BODY"
+	fi
+}
+
+_assert_header_contains() {
+	local needle=$1 label=$2
+	if printf '%s' "$CURL_HDR" | grep -qi -- "$needle"; then
+		_pass "$label"
+	else
+		_fail "$label" "needle '$needle' not in response headers" \
+			"headers: $(printf '%s' "$CURL_HDR" | head -c 400)"
+	fi
+}
+
+if ! command -v jq >/dev/null 2>&1; then
+	_die "jq is required. brew install jq."
+fi
+if ! curl -s -o /dev/null --max-time 2 "$HOST/api/v0/version" 2>/dev/null; then
+	_die "amuleapi at $HOST is not reachable. Start amuleapi first."
+fi
+
+echo "amuleapi 02-auth smoke @ $HOST"
+
+# --- 1. Login with wrong password → 401 invalid_credentials. -------
+_curl -X POST -H "Content-Type: application/json" \
+	-d '{"password":"wrong-password"}' \
+	"$HOST/api/v0/auth/login?type=bearer"
+_assert_status 401 "POST /auth/login with wrong password → 401"
+_assert_json_eq '.error.code' invalid_credentials \
+	'401 carries error.code=invalid_credentials'
+
+# --- 2. Login with right password → 200 + JWT + Set-Cookie. --------
+_curl -X POST -H "Content-Type: application/json" \
+	-d "{\"password\":\"$ADMIN_PASS\"}" \
+	"$HOST/api/v0/auth/login?type=bearer"
+_assert_status 200 "POST /auth/login with admin password → 200"
+_assert_json_eq '.role'                    admin    'login response role=admin'
+_assert_json_eq '.token | length > 100'    true     'login response carries a real JWT (>100 chars)'
+_assert_json_eq '.expires_at | length'     20       'expires_at is 20-char ISO-8601'
+_assert_json_eq '.expires_at_unix | type'  number   'expires_at_unix is numeric'
+_assert_json_eq '.jti | length'            22       'jti is 22-char base64url'
+_assert_header_contains 'set-cookie: amuleapi_token=' \
+	'login sets the amuleapi_token cookie'
+_assert_header_contains 'HttpOnly' \
+	'cookie carries HttpOnly attribute'
+_assert_header_contains 'SameSite=Strict' \
+	'cookie carries SameSite=Strict attribute'
+
+# Stash the token for the next blocks.
+TOKEN=$(printf '%s' "$CURL_BODY" | jq -r .token)
+[ -n "$TOKEN" ] && [ "$TOKEN" != "null" ] \
+	|| _die "couldn't extract token from login response: $CURL_BODY"
+
+# --- 3. /auth/session with bearer → 200 + role/jti/exp. ------------
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/auth/session"
+_assert_status 200 "GET /auth/session (bearer) → 200"
+_assert_json_eq '.role' admin 'session.role=admin (bearer)'
+_assert_json_eq '.jti  | length' 22 'session.jti is 22-char (bearer)'
+_assert_json_eq '.exp  | length' 20 'session.exp is 20-char ISO-8601 (bearer)'
+
+# --- 4. /auth/session with cookie → same. --------------------------
+# Use the cookie jar populated by curl above by re-sending the same
+# header verbatim — simulates what a browser would do automatically.
+_curl -b "amuleapi_token=$TOKEN" "$HOST/api/v0/auth/session"
+_assert_status 200 "GET /auth/session (cookie) → 200"
+_assert_json_eq '.role' admin 'session.role=admin (cookie)'
+
+# --- 5. /auth/session with no creds → 401 unauthorized. ------------
+_curl "$HOST/api/v0/auth/session"
+_assert_status 401 "GET /auth/session (no creds) → 401"
+_assert_json_eq '.error.code' unauthorized \
+	'no-creds 401 carries error.code=unauthorized'
+
+# --- 6. /auth/session with bogus bearer → 401. ---------------------
+_curl -H "Authorization: Bearer not.a.real.jwt" "$HOST/api/v0/auth/session"
+_assert_status 401 "GET /auth/session (bogus bearer) → 401"
+
+# --- 7. /auth/logout (bearer) → 200 + clearing Set-Cookie. ---------
+_curl -X POST -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/auth/logout"
+_assert_status 200 "POST /auth/logout (bearer) → 200"
+_assert_json_eq '.ok' true 'logout body acks {ok:true}'
+_assert_header_contains 'set-cookie: amuleapi_token=;' \
+	'logout sends a clearing Set-Cookie'
+
+# --- 8. /auth/session with same (now revoked) bearer → 401. --------
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/auth/session"
+_assert_status 401 "GET /auth/session (revoked bearer) → 401"
+_assert_json_eq '.error.code' unauthorized \
+	'revoked bearer 401 carries error.code=unauthorized'
+
+# --- 9. Method gate. ----------------------------------------------
+_curl -X GET "$HOST/api/v0/auth/login?type=bearer"
+_assert_status 405 "GET /auth/login → 405 method_not_allowed"
+_curl -X GET "$HOST/api/v0/auth/logout"
+_assert_status 405 "GET /auth/logout → 405 method_not_allowed"
+
+# --- 10. Bad JSON body on login → 400 bad_request. -----------------
+_curl -X POST -H "Content-Type: application/json" \
+	-d 'not-even-json' \
+	"$HOST/api/v0/auth/login?type=bearer"
+_assert_status 400 "POST /auth/login (bad JSON) → 400"
+_assert_json_eq '.error.code' bad_request \
+	'bad-JSON 400 carries error.code=bad_request'
+
+# --- 11. Rate-limit: 5 wrong passwords (default threshold) → 429 ---
+# Defaults from amuleapi.conf: LoginFailureWindowSeconds=60,
+# LoginFailureThreshold=5, LoginLockoutSeconds=300.
+#
+# Boundary check: Check() runs BEFORE the password compare, then
+# NoteFailure() runs AFTER a wrong-password reject. So with
+# threshold=5:
+#   attempts 1-5  → status 401 (bucket grows 1..5; NoteFailure on
+#                   the 5th sets lockout_until)
+#   attempts 6+   → status 429 (the Check at the top of attempt 6
+#                   is the first one that observes lockout_until > now)
+# This pins the off-by-one boundary so a regression that arms the
+# lockout one attempt early (or late) trips the assertion.
+for i in 1 2 3 4; do
+	_curl -X POST -H "Content-Type: application/json" \
+		-d '{"password":"wrong"}' \
+		"$HOST/api/v0/auth/login?type=bearer" > /dev/null
+done
+# Attempt 5: NoteFailure() arms the lockout AFTER returning 401.
+_curl -X POST -H "Content-Type: application/json" \
+	-d '{"password":"wrong"}' \
+	"$HOST/api/v0/auth/login?type=bearer"
+_assert_status 401 "POST /auth/login: 5th failure arms but still returns 401"
+# Attempt 6: Check() sees the armed lockout → 429.
+_curl -X POST -H "Content-Type: application/json" \
+	-d '{"password":"wrong"}' \
+	"$HOST/api/v0/auth/login?type=bearer"
+_assert_status 429 "POST /auth/login: 6th attempt is the first 429"
+_assert_json_eq '.error.code' rate_limited \
+	'6th-attempt lockout carries error.code=rate_limited'
+
+# Attempt 7 stays locked.
+_curl -X POST -H "Content-Type: application/json" \
+	-d '{"password":"wrong"}' \
+	"$HOST/api/v0/auth/login?type=bearer" > /dev/null
+# The 8th attempt also remains locked.
+_curl -X POST -H "Content-Type: application/json" \
+	-d '{"password":"wrong"}' \
+	"$HOST/api/v0/auth/login?type=bearer"
+_assert_status 429 "POST /auth/login after many failures → 429"
+_assert_json_eq '.error.code' rate_limited \
+	'lockout carries error.code=rate_limited'
+_assert_header_contains 'retry-after:' \
+	'lockout carries Retry-After header'
+
+# --- Summary. -----------------------------------------------------
+echo
+if [ "$FAIL_COUNT" -eq 0 ]; then
+	echo "OK: $TEST_COUNT/$TEST_COUNT passed"
+	exit 0
+fi
+echo "FAIL: $FAIL_COUNT/$TEST_COUNT failed"
+exit 1
diff --git a/unittests/curl-tests/amuleapi/03-read-status.sh b/unittests/curl-tests/amuleapi/03-read-status.sh
new file mode 100755
index 0000000000..78259d8d7a
--- /dev/null
+++ b/unittests/curl-tests/amuleapi/03-read-status.sh
@@ -0,0 +1,177 @@
+#!/usr/bin/env bash
+#
+# amuleapi 03-read-status — read endpoints, /status only. Validates the
+# refresher → state cache → handler chain end-to-end against a live
+# amuled. The remaining 12 endpoints (downloads, uploads, shared,
+# servers, kad, categories, logs/amule, logs/serverinfo, preferences,
+# stats/tree, stats/graphs, search/results) land in subsequent
+# sub-phases (4b/4c/4d); their phase scripts share this directory.
+#
+# Bring-up convention:
+#   rm -rf /tmp/amuleapi-03-read-status && mkdir -p /tmp/amuleapi-03-read-status
+#   amuleapi --config-dir=/tmp/amuleapi-03-read-status --host=127.0.0.1 \
+#            --port=4712 --password=amule --set-admin-pass=adminpass
+#   amuleapi --config-dir=/tmp/amuleapi-03-read-status --host=127.0.0.1 \
+#            --port=4712 --password=amule &
+#   ./03-read-status.sh
+#
+# Environment:
+#   HOST=localhost:4713          amuleapi endpoint
+#   ADMIN_PASS=adminpass         plaintext admin password
+#   GUEST_PASS=guestpass         plaintext guest password (run-all.sh
+#                                configures it via --set-guest-pass;
+#                                standalone invocations need this set
+#                                or the guest-read assertion is skipped)
+#
+# Exits 0 on success, 1 on assertion failure, 2 on bring-up error.
+
+set -u
+set -o pipefail
+
+HOST=${HOST:-localhost:4713}
+ADMIN_PASS=${ADMIN_PASS:-adminpass}
+GUEST_PASS=${GUEST_PASS:-guestpass}
+
+FAIL_COUNT=0
+TEST_COUNT=0
+
+CURL_BODY_FILE=$(mktemp -t amuleapi_03_read_status_body.XXXXXX)
+trap 'rm -f "$CURL_BODY_FILE"' EXIT
+
+_die()  { echo "FATAL: $*" >&2; exit 2; }
+_pass() { TEST_COUNT=$((TEST_COUNT+1)); echo "  PASS  $1"; }
+_fail() {
+	TEST_COUNT=$((TEST_COUNT+1)); FAIL_COUNT=$((FAIL_COUNT+1))
+	echo "  FAIL  $1"
+	shift
+	for arg in "$@"; do echo "        $arg"; done
+}
+
+_curl() {
+	local resp
+	resp=$(curl -s --max-time 10 \
+		-o "$CURL_BODY_FILE" -w '%{http_code}' "$@") \
+		|| _die "curl invocation failed for $*"
+	CURL_STATUS=$resp
+	CURL_BODY=$(cat "$CURL_BODY_FILE")
+}
+
+_assert_status() {
+	local expected=$1 label=$2
+	if [ "$CURL_STATUS" = "$expected" ]; then
+		_pass "$label (HTTP $CURL_STATUS)"
+	else
+		_fail "$label" "expected HTTP $expected, got $CURL_STATUS" \
+			"body head: $(printf '%s' "$CURL_BODY" | head -c 200)"
+	fi
+}
+
+_assert_json_eq() {
+	local expr=$1 expected=$2 label=$3
+	local actual
+	actual=$(printf '%s' "$CURL_BODY" | jq -r "$expr" 2>/dev/null) \
+		|| _fail "$label" "body was not valid JSON" "body: $CURL_BODY"
+	if [ "$actual" = "$expected" ]; then
+		_pass "$label"
+	else
+		_fail "$label" "expected $expected, got $actual" "body: $CURL_BODY"
+	fi
+}
+
+if ! command -v jq >/dev/null 2>&1; then
+	_die "jq is required. brew install jq."
+fi
+if ! curl -s -o /dev/null --max-time 2 "$HOST/api/v0/version" 2>/dev/null; then
+	_die "amuleapi at $HOST is not reachable. Start amuleapi first."
+fi
+
+echo "amuleapi 03-read-status smoke @ $HOST"
+
+# --- 1. /status without auth → 401 unauthorized. -------------------
+_curl "$HOST/api/v0/status"
+_assert_status 401 "GET /api/v0/status (no creds) → 401"
+_assert_json_eq '.error.code' unauthorized \
+	'unauthenticated /status carries error.code=unauthorized'
+
+# --- 2. Log in as admin and capture the bearer. --------------------
+TOKEN=$(curl -s -X POST -H "Content-Type: application/json" \
+	-d "{\"password\":\"$ADMIN_PASS\"}" \
+	"$HOST/api/v0/auth/login?type=bearer" | jq -r .token)
+[ -n "$TOKEN" ] && [ "$TOKEN" != "null" ] \
+	|| _die "could not log in for /status tests"
+
+# Wait for the refresher to land its first snapshot. On a fast
+# Linux host the first tick is sub-second; on the Windows VM the
+# 503 ec_unavailable window can stretch a few seconds under load.
+# Poll up to 15 s, same shape run-all.sh uses for /version, so
+# the test doesn't drift to "disconnected" under runner pressure.
+for _ in $(seq 1 30); do
+	probe=$(curl -s -o /dev/null -w "%{http_code}" \
+		-H "Authorization: Bearer $TOKEN" \
+		"$HOST/api/v0/status")
+	[ "$probe" = "200" ] && break
+	sleep 0.5
+done
+
+# --- 3. /status with bearer → 200 + envelope shape. ----------------
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/status"
+_assert_status 200 "GET /api/v0/status (admin bearer) → 200"
+
+# Envelope metadata.
+_assert_json_eq '.ec_connected | type' boolean \
+	'ec_connected is boolean'
+
+# ed2k subtree.
+_assert_json_eq '.ed2k.state | test("^(connected|connecting|disconnected)$")' \
+	true 'ed2k.state is a known enum value'
+_assert_json_eq '.ed2k.low_id | type' boolean \
+	'ed2k.low_id is boolean'
+_assert_json_eq '.ed2k.server_name | type' string \
+	'ed2k.server_name is string'
+
+# kad subtree.
+_assert_json_eq '.kad.state | test("^(connected|connecting|disabled)$")' \
+	true 'kad.state is a known enum value'
+_assert_json_eq '.kad.firewalled | type' boolean \
+	'kad.firewalled is boolean'
+
+# speeds + queue subtrees.
+_assert_json_eq '.speeds.download_bps | type' number \
+	'speeds.download_bps is numeric'
+_assert_json_eq '.speeds.upload_bps | type' number \
+	'speeds.upload_bps is numeric'
+_assert_json_eq '.queue.upload_queue_length | type' number \
+	'queue.upload_queue_length is numeric'
+_assert_json_eq '.queue.total_source_count | type' number \
+	'queue.total_source_count is numeric'
+
+# --- 4. /status with guest bearer also works (any-role read gate). --
+GUEST_TOKEN=$(curl -s -X POST -H "Content-Type: application/json" \
+	-d "{\"password\":\"$GUEST_PASS\"}" \
+	"$HOST/api/v0/auth/login?type=bearer" | jq -r .token)
+if [ -n "$GUEST_TOKEN" ] && [ "$GUEST_TOKEN" != "null" ]; then
+	_curl -H "Authorization: Bearer $GUEST_TOKEN" "$HOST/api/v0/status"
+	_assert_status 200 "GET /api/v0/status (guest bearer) → 200"
+else
+	# run-all.sh always configures a guest password; if a future
+	# fixture drops it, surface the gap rather than silently
+	# pretending the guest read-gate was exercised.
+	_die "guest login failed in 03-read-status fixture — 03-read-status is supposed to verify both roles can read /status; check that GUEST_PASS is wired"
+fi
+
+# --- 5. Method gate. ----------------------------------------------
+_curl -X DELETE -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/status"
+_assert_status 405 "DELETE /api/v0/status → 405 method_not_allowed"
+
+# --- 6. HEAD /status. ----------------------------------------------
+_curl -I -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/status"
+_assert_status 200 "HEAD /api/v0/status → 200"
+
+# --- Summary. -----------------------------------------------------
+echo
+if [ "$FAIL_COUNT" -eq 0 ]; then
+	echo "OK: $TEST_COUNT/$TEST_COUNT passed"
+	exit 0
+fi
+echo "FAIL: $FAIL_COUNT/$TEST_COUNT failed"
+exit 1
diff --git a/unittests/curl-tests/amuleapi/04-read-downloads-shared.sh b/unittests/curl-tests/amuleapi/04-read-downloads-shared.sh
new file mode 100755
index 0000000000..83f44fea8d
--- /dev/null
+++ b/unittests/curl-tests/amuleapi/04-read-downloads-shared.sh
@@ -0,0 +1,191 @@
+#!/usr/bin/env bash
+#
+# amuleapi /downloads, /downloads/{hash}, /shared. Exercises the
+# consolidated GET_UPDATE @ EC_DETAIL_INC_UPDATE polling path end-
+# to-end, the ECID-keyed state cache, the auth gate, and the bare-
+# object detail shape.
+#
+# This smoke is intentionally tolerant of empty caches — it asserts
+# the envelope shape and the per-item field types without requiring
+# a specific download / upload / shared file to exist on the daemon.
+# Field-content correctness is exercised by the unit tests against
+# crafted EC packets, and by the live test the dev runs against
+# their daemon (`./build-macos/src/webapi/amuleapi ...` →
+# `curl /downloads | jq`).
+#
+# Bring-up convention:
+#   rm -rf /tmp/amuleapi-04-read-downloads-shared && mkdir -p /tmp/amuleapi-04-read-downloads-shared
+#   amuleapi --config-dir=/tmp/amuleapi-04-read-downloads-shared --host=127.0.0.1 \
+#            --port=4712 --password=amule --set-admin-pass=adminpass
+#   amuleapi --config-dir=/tmp/amuleapi-04-read-downloads-shared --host=127.0.0.1 \
+#            --port=4712 --password=amule &
+#   ./04-read-downloads-shared.sh
+
+set -u
+set -o pipefail
+
+HOST=${HOST:-localhost:4713}
+ADMIN_PASS=${ADMIN_PASS:-adminpass}
+
+FAIL_COUNT=0
+TEST_COUNT=0
+
+CURL_BODY_FILE=$(mktemp -t amuleapi_04_read_downloads_shared_body.XXXXXX)
+trap 'rm -f "$CURL_BODY_FILE"' EXIT
+
+_die()  { echo "FATAL: $*" >&2; exit 2; }
+_pass() { TEST_COUNT=$((TEST_COUNT+1)); echo "  PASS  $1"; }
+_fail() {
+	TEST_COUNT=$((TEST_COUNT+1)); FAIL_COUNT=$((FAIL_COUNT+1))
+	echo "  FAIL  $1"
+	shift
+	for arg in "$@"; do echo "        $arg"; done
+}
+
+_curl() {
+	local resp
+	resp=$(curl -s --max-time 10 \
+		-o "$CURL_BODY_FILE" -w '%{http_code}' "$@") \
+		|| _die "curl invocation failed for $*"
+	CURL_STATUS=$resp
+	CURL_BODY=$(cat "$CURL_BODY_FILE")
+}
+
+_assert_status() {
+	local expected=$1 label=$2
+	if [ "$CURL_STATUS" = "$expected" ]; then
+		_pass "$label (HTTP $CURL_STATUS)"
+	else
+		_fail "$label" "expected HTTP $expected, got $CURL_STATUS" \
+			"body head: $(printf '%s' "$CURL_BODY" | head -c 200)"
+	fi
+}
+
+_assert_json_eq() {
+	local expr=$1 expected=$2 label=$3
+	local actual
+	actual=$(printf '%s' "$CURL_BODY" | jq -r "$expr" 2>/dev/null) \
+		|| _fail "$label" "body was not valid JSON" "body: $CURL_BODY"
+	if [ "$actual" = "$expected" ]; then
+		_pass "$label"
+	else
+		_fail "$label" "expected $expected, got $actual" "body: $CURL_BODY"
+	fi
+}
+
+if ! command -v jq >/dev/null 2>&1; then
+	_die "jq is required. brew install jq."
+fi
+if ! curl -s -o /dev/null --max-time 2 "$HOST/api/v0/version" 2>/dev/null; then
+	_die "amuleapi at $HOST is not reachable. Start amuleapi first."
+fi
+
+echo "amuleapi 04-read-downloads-shared smoke @ $HOST"
+
+# --- 0. Log in. ----------------------------------------------------
+TOKEN=$(curl -s -X POST -H "Content-Type: application/json" \
+	-d "{\"password\":\"$ADMIN_PASS\"}" \
+	"$HOST/api/v0/auth/login?type=bearer" | jq -r .token)
+[ -n "$TOKEN" ] && [ "$TOKEN" != "null" ] \
+	|| _die "could not log in for phase 4b tests"
+
+# Allow the first two refresher ticks to populate the cache (cold
+# start: Phase 1 surfaces every existing file as "new", Phase 2 ships
+# their identities; from tick 2 the cache is fully built).
+sleep 3
+
+# --- 1. Each list endpoint pre-auth → 401. -------------------------
+for ep in downloads shared; do
+	_curl "$HOST/api/v0/$ep"
+	_assert_status 401 "GET /api/v0/$ep without creds → 401"
+done
+
+# --- 2. List endpoints with admin bearer → 200 + envelope shape. ---
+for ep in downloads shared; do
+	_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/$ep"
+	_assert_status 200 "GET /api/v0/$ep (admin bearer) → 200"
+	_assert_json_eq ".$ep | type"                array   "/$ep .$ep is an array"
+done
+
+# --- 3. /downloads element shape (only when there's at least one). -
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/downloads"
+COUNT=$(printf '%s' "$CURL_BODY" | jq '.downloads | length')
+if [ "$COUNT" -gt 0 ]; then
+	echo "  --- /downloads has $COUNT entry/entries; shape checks ---"
+	_assert_json_eq '.downloads[0].hash | length' 32 \
+		'/downloads[0].hash is 32-char hex'
+	_assert_json_eq '.downloads[0].ecid | type' null \
+		'/downloads[0] does not expose internal ecid'
+	_assert_json_eq '.downloads[0].name | type' string \
+		'/downloads[0].name is string'
+	_assert_json_eq '.downloads[0].size | type' number \
+		'/downloads[0].size is numeric'
+	_assert_json_eq '.downloads[0].status | test("^(downloading|paused|completed|hashing|erroneous|completing|allocating|waiting|insufficient_disk|unknown)$")' \
+		true '/downloads[0].status is a known enum value'
+	_assert_json_eq '.downloads[0].priority | test("^(very_low|low|normal|high|release|auto)$")' \
+		true '/downloads[0].priority is a known enum value'
+	_assert_json_eq '.downloads[0].progress.percent | type' number \
+		'/downloads[0].progress.percent is numeric'
+	_assert_json_eq '.downloads[0].sources | type' object \
+		'/downloads[0].sources is object'
+	_assert_json_eq '.downloads[0].sources.total | type' number \
+		'/downloads[0].sources.total is numeric'
+
+	# --- 4. /downloads/{hash} bare-object detail. -----------------
+	HASH=$(printf '%s' "$CURL_BODY" | jq -r '.downloads[0].hash')
+	_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/downloads/$HASH"
+	_assert_status 200 "GET /api/v0/downloads/{hash} → 200"
+	# Detail response is bare — `hash` at top level, no `snapshot_at`
+	# envelope (Q3 in PLAN.md §12).
+	_assert_json_eq '.hash' "$HASH" '/downloads/{hash} returns bare object keyed by hash'
+	_assert_json_eq '.snapshot_at | type' null \
+		'/downloads/{hash} has no snapshot_at envelope (bare object)'
+	_assert_json_eq '.progress.percent | type' number \
+		'/downloads/{hash} carries progress.percent'
+
+	# Uppercase hash → same hit (case-insensitive route).
+	HASH_UPPER=$(echo "$HASH" | tr '[:lower:]' '[:upper:]')
+	_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/downloads/$HASH_UPPER"
+	_assert_status 200 "GET /downloads/{HASH-UPPERCASE} → 200 (case-insensitive)"
+else
+	echo "  --- /downloads is empty; skipping per-item shape + detail checks ---"
+fi
+
+# --- 5. Missing-hash 404. -----------------------------------------
+_curl -H "Authorization: Bearer $TOKEN" \
+	"$HOST/api/v0/downloads/baadbaadbaadbaadbaadbaadbaadbaad"
+_assert_status 404 "GET /downloads/{nonexistent-hash} → 404"
+_assert_json_eq '.error.code' not_found \
+	'404 carries error.code=not_found'
+
+# --- 6. /shared element shape (always at least .DS_Store on macOS). -
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/shared"
+SHCOUNT=$(printf '%s' "$CURL_BODY" | jq '.shared | length')
+if [ "$SHCOUNT" -gt 0 ]; then
+	echo "  --- /shared has $SHCOUNT entry/entries; shape checks ---"
+	_assert_json_eq '.shared[0].hash | length' 32 \
+		'/shared[0].hash is 32-char hex'
+	_assert_json_eq '.shared[0].ecid | type' null \
+		'/shared[0] does not expose internal ecid'
+	_assert_json_eq '.shared[0].xfer | type' object \
+		'/shared[0].xfer is object'
+	_assert_json_eq '.shared[0].xfer.total | type' number \
+		'/shared[0].xfer.total is numeric'
+	_assert_json_eq '.shared[0].priority | type' string \
+		'/shared[0].priority is string'
+fi
+
+# --- 7. Method gate (POST/DELETE not allowed on read-only). -------
+for ep in downloads shared; do
+	_curl -X DELETE -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/$ep"
+	_assert_status 405 "DELETE /api/v0/$ep → 405"
+done
+
+# --- Summary. -----------------------------------------------------
+echo
+if [ "$FAIL_COUNT" -eq 0 ]; then
+	echo "OK: $TEST_COUNT/$TEST_COUNT passed"
+	exit 0
+fi
+echo "FAIL: $FAIL_COUNT/$TEST_COUNT failed"
+exit 1
diff --git a/unittests/curl-tests/amuleapi/05-read-servers-kad-categories-prefs.sh b/unittests/curl-tests/amuleapi/05-read-servers-kad-categories-prefs.sh
new file mode 100755
index 0000000000..a34feede37
--- /dev/null
+++ b/unittests/curl-tests/amuleapi/05-read-servers-kad-categories-prefs.sh
@@ -0,0 +1,175 @@
+#!/usr/bin/env bash
+#
+# amuleapi 05-read-servers-kad-categories-prefs — /servers, /kad, /categories, /preferences.
+# Exercises the four endpoints added in this sub-phase. Tolerant of
+# empty caches (e.g. amuled with no configured servers) — asserts
+# envelope shape + per-item field types without requiring specific
+# content.
+#
+# Bring-up:
+#   amuleapi --config-dir=/tmp/amuleapi-05-read-servers-kad-categories-prefs \
+#            --host=127.0.0.1 --port=4712 --password=amule \
+#            --set-admin-pass=adminpass
+#   amuleapi --config-dir=/tmp/amuleapi-05-read-servers-kad-categories-prefs ... &
+#   ./05-read-servers-kad-categories-prefs.sh
+
+set -u
+set -o pipefail
+
+HOST=${HOST:-localhost:4713}
+ADMIN_PASS=${ADMIN_PASS:-adminpass}
+
+FAIL_COUNT=0
+TEST_COUNT=0
+
+CURL_BODY_FILE=$(mktemp -t amuleapi_05_read_servers_kad_categories_prefs_body.XXXXXX)
+trap 'rm -f "$CURL_BODY_FILE"' EXIT
+
+_die()  { echo "FATAL: $*" >&2; exit 2; }
+_pass() { TEST_COUNT=$((TEST_COUNT+1)); echo "  PASS  $1"; }
+_fail() {
+	TEST_COUNT=$((TEST_COUNT+1)); FAIL_COUNT=$((FAIL_COUNT+1))
+	echo "  FAIL  $1"
+	shift
+	for arg in "$@"; do echo "        $arg"; done
+}
+
+_curl() {
+	local resp
+	resp=$(curl -s --max-time 10 -o "$CURL_BODY_FILE" -w '%{http_code}' "$@") \
+		|| _die "curl invocation failed for $*"
+	CURL_STATUS=$resp
+	CURL_BODY=$(cat "$CURL_BODY_FILE")
+}
+
+_assert_status() {
+	local expected=$1 label=$2
+	if [ "$CURL_STATUS" = "$expected" ]; then
+		_pass "$label (HTTP $CURL_STATUS)"
+	else
+		_fail "$label" "expected HTTP $expected, got $CURL_STATUS" \
+			"body head: $(printf '%s' "$CURL_BODY" | head -c 200)"
+	fi
+}
+
+_assert_json_eq() {
+	local expr=$1 expected=$2 label=$3
+	local actual
+	actual=$(printf '%s' "$CURL_BODY" | jq -r "$expr" 2>/dev/null) \
+		|| _fail "$label" "body was not valid JSON" "body: $CURL_BODY"
+	if [ "$actual" = "$expected" ]; then
+		_pass "$label"
+	else
+		_fail "$label" "expected $expected, got $actual" "body: $CURL_BODY"
+	fi
+}
+
+if ! command -v jq >/dev/null 2>&1; then
+	_die "jq is required."
+fi
+if ! curl -s -o /dev/null --max-time 2 "$HOST/api/v0/version" 2>/dev/null; then
+	_die "amuleapi at $HOST is not reachable."
+fi
+
+echo "amuleapi 05-read-servers-kad-categories-prefs smoke @ $HOST"
+
+# Log in.
+TOKEN=$(curl -s -X POST -H "Content-Type: application/json" \
+	-d "{\"password\":\"$ADMIN_PASS\"}" \
+	"$HOST/api/v0/auth/login?type=bearer" | jq -r .token)
+[ -n "$TOKEN" ] && [ "$TOKEN" != "null" ] || _die "login failed"
+
+# Wait for the first full refresher tick (servers + prefs land at the
+# end of the tick — we need the second tick to confirm steady-state).
+sleep 3
+
+# --- 1. /servers ---------------------------------------------------
+_curl "$HOST/api/v0/servers"
+_assert_status 401 "GET /servers (no creds) → 401"
+
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/servers"
+_assert_status 200 "GET /servers (admin) → 200"
+_assert_json_eq '.servers | type'          array  '/servers .servers is an array'
+COUNT=$(printf '%s' "$CURL_BODY" | jq '.servers | length')
+if [ "$COUNT" -gt 0 ]; then
+	echo "  --- /servers has $COUNT entry/entries; per-item shape ---"
+	_assert_json_eq '.servers[0].name     | type' string  '/servers[0].name is string'
+	_assert_json_eq '.servers[0].address  | type' string  '/servers[0].address is string'
+	_assert_json_eq '.servers[0].port     | type' number  '/servers[0].port is numeric'
+	_assert_json_eq '.servers[0].users    | type' number  '/servers[0].users is numeric'
+	_assert_json_eq '.servers[0].priority | test("^(low|normal|high)$")' \
+		true '/servers[0].priority is a known enum value'
+	_assert_json_eq '.servers[0].static   | type' boolean '/servers[0].static is boolean'
+fi
+
+# --- 2. /kad -------------------------------------------------------
+_curl "$HOST/api/v0/kad"
+_assert_status 401 "GET /kad (no creds) → 401"
+
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/kad"
+_assert_status 200 "GET /kad (admin) → 200"
+_assert_json_eq '.state | test("^(disabled|connecting|connected)$")' \
+	true '/kad.state is a known enum value'
+_assert_json_eq '.firewalled       | type' boolean '/kad.firewalled is boolean'
+_assert_json_eq '.firewalled_udp   | type' boolean '/kad.firewalled_udp is boolean'
+_assert_json_eq '.in_lan_mode      | type' boolean '/kad.in_lan_mode is boolean'
+_assert_json_eq '.ip               | type' string  '/kad.ip is string'
+_assert_json_eq '.network.users    | type' number  '/kad.network.users is numeric'
+_assert_json_eq '.network.files    | type' number  '/kad.network.files is numeric'
+_assert_json_eq '.network.nodes    | type' number  '/kad.network.nodes is numeric'
+_assert_json_eq '.indexed.sources  | type' number  '/kad.indexed.sources is numeric'
+_assert_json_eq '.buddy.status     | test("^(no_buddy|connecting|connected|unknown)$")' \
+	true '/kad.buddy.status is a known enum value'
+
+# --- 3. /categories -----------------------------------------------
+_curl "$HOST/api/v0/categories"
+_assert_status 401 "GET /categories (no creds) → 401"
+
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/categories"
+_assert_status 200 "GET /categories (admin) → 200"
+_assert_json_eq '.categories | type' array '/categories.categories is an array'
+CATCOUNT=$(printf '%s' "$CURL_BODY" | jq '.categories | length')
+if [ "$CATCOUNT" -gt 0 ]; then
+	echo "  --- /categories has $CATCOUNT entry/entries; per-item shape ---"
+	_assert_json_eq '.categories[0].index | type' number '/categories[0].index is numeric'
+	_assert_json_eq '.categories[0].name  | type' string '/categories[0].name is string'
+	_assert_json_eq '.categories[0].priority | test("^(very_low|low|normal|high|release|auto)$")' \
+		true '/categories[0].priority is a known enum value'
+fi
+
+# --- 4. /preferences ----------------------------------------------
+_curl "$HOST/api/v0/preferences"
+_assert_status 401 "GET /preferences (no creds) → 401"
+
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/preferences"
+_assert_status 200 "GET /preferences (admin) → 200"
+# Bare object (no envelope) per Q3 — preferences is a single resource.
+_assert_json_eq '.snapshot_at | type' null \
+	'/preferences has no snapshot_at envelope (bare object)'
+
+_assert_json_eq '.general.nickname             | type' string  '/preferences.general.nickname is string'
+_assert_json_eq '.general.user_hash | length'                          32   '/preferences.general.user_hash is 32-char hex'
+_assert_json_eq '.general.check_new_version    | type' boolean '/preferences.general.check_new_version is boolean'
+
+_assert_json_eq '.connection.tcp_port          | type' number  '/preferences.connection.tcp_port is numeric'
+_assert_json_eq '.connection.udp_port          | type' number  '/preferences.connection.udp_port is numeric'
+_assert_json_eq '.connection.udp_disabled      | type' boolean '/preferences.connection.udp_disabled is boolean'
+_assert_json_eq '.connection.network_ed2k      | type' boolean '/preferences.connection.network_ed2k is boolean'
+_assert_json_eq '.connection.network_kad       | type' boolean '/preferences.connection.network_kad is boolean'
+_assert_json_eq '.connection.autoconnect       | type' boolean '/preferences.connection.autoconnect is boolean'
+_assert_json_eq '.connection.max_sources_per_file | type' number '/preferences.connection.max_sources_per_file is numeric'
+
+# --- Method gate. ----------------------------------------------
+for ep in servers kad categories preferences; do
+	_curl -X DELETE -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/$ep"
+	_assert_status 405 "DELETE /api/v0/$ep → 405"
+done
+
+# --- Summary. -----------------------------------------------------
+echo
+if [ "$FAIL_COUNT" -eq 0 ]; then
+	echo "OK: $TEST_COUNT/$TEST_COUNT passed"
+	exit 0
+fi
+echo "FAIL: $FAIL_COUNT/$TEST_COUNT failed"
+exit 1
diff --git a/unittests/curl-tests/amuleapi/06-read-logs.sh b/unittests/curl-tests/amuleapi/06-read-logs.sh
new file mode 100755
index 0000000000..823d4ee9ce
--- /dev/null
+++ b/unittests/curl-tests/amuleapi/06-read-logs.sh
@@ -0,0 +1,157 @@
+#!/usr/bin/env bash
+#
+# amuleapi 06-read-logs — /logs/amule + /logs/serverinfo. amule log
+# rides on STAT_REQ's `EC_TAG_STATS_LOGGER_MESSAGE` channel (per-EC-
+# connection cursor, incremental); server-info log is full-snapshot
+# via `EC_OP_GET_SERVERINFO`.
+#
+# Bring-up:
+#   amuleapi --config-dir=/tmp/amuleapi-06-read-logs ... &
+#   ./06-read-logs.sh
+
+set -u
+set -o pipefail
+
+HOST=${HOST:-localhost:4713}
+ADMIN_PASS=${ADMIN_PASS:-adminpass}
+
+FAIL_COUNT=0
+TEST_COUNT=0
+
+CURL_BODY_FILE=$(mktemp -t amuleapi_06_read_logs_body.XXXXXX)
+trap 'rm -f "$CURL_BODY_FILE"' EXIT
+
+_die()  { echo "FATAL: $*" >&2; exit 2; }
+_pass() { TEST_COUNT=$((TEST_COUNT+1)); echo "  PASS  $1"; }
+_fail() {
+	TEST_COUNT=$((TEST_COUNT+1)); FAIL_COUNT=$((FAIL_COUNT+1))
+	echo "  FAIL  $1"
+	shift
+	for arg in "$@"; do echo "        $arg"; done
+}
+
+_curl() {
+	local resp
+	resp=$(curl -s --max-time 10 -o "$CURL_BODY_FILE" -w '%{http_code}' "$@") \
+		|| _die "curl invocation failed for $*"
+	CURL_STATUS=$resp
+	CURL_BODY=$(cat "$CURL_BODY_FILE")
+}
+
+_assert_status() {
+	local expected=$1 label=$2
+	if [ "$CURL_STATUS" = "$expected" ]; then
+		_pass "$label (HTTP $CURL_STATUS)"
+	else
+		_fail "$label" "expected HTTP $expected, got $CURL_STATUS" \
+			"body head: $(printf '%s' "$CURL_BODY" | head -c 200)"
+	fi
+}
+
+_assert_json_eq() {
+	local expr=$1 expected=$2 label=$3
+	local actual
+	actual=$(printf '%s' "$CURL_BODY" | jq -r "$expr" 2>/dev/null) \
+		|| _fail "$label" "body was not valid JSON" "body: $CURL_BODY"
+	if [ "$actual" = "$expected" ]; then
+		_pass "$label"
+	else
+		_fail "$label" "expected $expected, got $actual" "body: $CURL_BODY"
+	fi
+}
+
+if ! command -v jq >/dev/null 2>&1; then
+	_die "jq is required."
+fi
+if ! curl -s -o /dev/null --max-time 2 "$HOST/api/v0/version" 2>/dev/null; then
+	_die "amuleapi at $HOST is not reachable."
+fi
+
+echo "amuleapi 06-read-logs smoke @ $HOST"
+
+TOKEN=$(curl -s -X POST -H "Content-Type: application/json" \
+	-d "{\"password\":\"$ADMIN_PASS\"}" \
+	"$HOST/api/v0/auth/login?type=bearer" | jq -r .token)
+[ -n "$TOKEN" ] && [ "$TOKEN" != "null" ] || _die "login failed"
+
+# Give the refresher a few seconds to drain the initial log baseline
+# (CLoggerAccess emits the entire pre-connection backlog on its first
+# tick).
+sleep 5
+
+# --- 1. Auth gate. -------------------------------------------------
+_curl "$HOST/api/v0/logs/amule"
+_assert_status 401 "GET /logs/amule (no creds) → 401"
+_curl "$HOST/api/v0/logs/serverinfo"
+_assert_status 401 "GET /logs/serverinfo (no creds) → 401"
+
+# --- 2. /logs/amule full response shape. ---------------------------
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/logs/amule"
+_assert_status 200 "GET /logs/amule → 200"
+_assert_json_eq '.lines | type'         array  '/logs/amule.lines is an array'
+_assert_json_eq '.total_cached | type'  number '/logs/amule.total_cached is numeric'
+_assert_json_eq '.returned | type'      number '/logs/amule.returned is numeric'
+_assert_json_eq '.lines | length > 0'   true   '/logs/amule.lines is non-empty (amule emits a banner on connect)'
+# When no tail is given, returned == total_cached.
+_assert_json_eq '(.returned == .total_cached)' true \
+	'/logs/amule: returned == total_cached when no ?tail given'
+
+TOTAL=$(printf '%s' "$CURL_BODY" | jq '.total_cached')
+
+# --- 3. /logs/amule?tail=N. ----------------------------------------
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/logs/amule?tail=2"
+_assert_status 200 "GET /logs/amule?tail=2 → 200"
+_assert_json_eq '.returned'           2      '/logs/amule?tail=2 returns 2 lines'
+_assert_json_eq '.lines | length'     2      '/logs/amule?tail=2 array length is 2'
+_assert_json_eq '.total_cached'       "$TOTAL" '/logs/amule?tail=2 still reports full cached count'
+
+# tail=0 means "no tailing" → all lines. The wire contract makes 0
+# the inert default (matches the helper's behaviour: 0 = unbounded).
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/logs/amule?tail=0"
+_assert_status 200 "GET /logs/amule?tail=0 → 200"
+_assert_json_eq '(.returned == .total_cached)' true \
+	'/logs/amule?tail=0 returns all (tail=0 is "no tailing")'
+
+# Bogus / non-numeric tail clamps to 0 (return all).
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/logs/amule?tail=notanumber"
+_assert_status 200 "GET /logs/amule?tail=notanumber → 200"
+_assert_json_eq '(.returned == .total_cached)' true \
+	'/logs/amule?tail=<bogus> defaults to "no tailing"'
+
+# --- 4. /logs/serverinfo shape. ------------------------------------
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/logs/serverinfo"
+_assert_status 200 "GET /logs/serverinfo → 200"
+_assert_json_eq '.text | type'           string '/logs/serverinfo.text is string'
+_assert_json_eq '.total_bytes | type'    number '/logs/serverinfo.total_bytes is numeric'
+_assert_json_eq '.returned_bytes | type' number '/logs/serverinfo.returned_bytes is numeric'
+_assert_json_eq '(.returned_bytes == .total_bytes)' true \
+	'/logs/serverinfo: returned_bytes == total_bytes when no ?tail given'
+
+TOTAL_BYTES=$(printf '%s' "$CURL_BODY" | jq '.total_bytes')
+
+# --- 5. /logs/serverinfo?tail=3 — line-boundary slicing. -----------
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/logs/serverinfo?tail=3"
+_assert_status 200 "GET /logs/serverinfo?tail=3 → 200"
+_assert_json_eq '(.returned_bytes <= .total_bytes)' true \
+	'/logs/serverinfo?tail=3: returned_bytes <= total_bytes'
+_assert_json_eq '.total_bytes' "$TOTAL_BYTES" \
+	'/logs/serverinfo?tail=3 reports the same total_bytes'
+
+# --- 6. Method gate. -----------------------------------------------
+# DELETE on /logs/{amule,serverinfo} now CLEARS the buffer (phase 11
+# / RFC §4.11 alignment); the 405 contract this test originally
+# asserted has been retired. PATCH stays a 405 — the logs are
+# read+reset only, never partially mutable.
+for ep in logs/amule logs/serverinfo; do
+	_curl -X PATCH -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/$ep"
+	_assert_status 405 "PATCH /api/v0/$ep → 405"
+done
+
+# --- Summary. -----------------------------------------------------
+echo
+if [ "$FAIL_COUNT" -eq 0 ]; then
+	echo "OK: $TEST_COUNT/$TEST_COUNT passed"
+	exit 0
+fi
+echo "FAIL: $FAIL_COUNT/$TEST_COUNT failed"
+exit 1
diff --git a/unittests/curl-tests/amuleapi/07-read-stats-and-search-results.sh b/unittests/curl-tests/amuleapi/07-read-stats-and-search-results.sh
new file mode 100755
index 0000000000..3e065e6324
--- /dev/null
+++ b/unittests/curl-tests/amuleapi/07-read-stats-and-search-results.sh
@@ -0,0 +1,159 @@
+#!/usr/bin/env bash
+#
+# amuleapi 07-read-stats-and-search-results — /stats/tree, /stats/graphs/{graph}, /search/results.
+# /stats/tree is a recursive structure; /stats/graphs is a time-series with
+# per-graph path-param + ?width=N tailing; /search/results is read-only
+# until Phase 5 adds POST /search.
+
+set -u
+set -o pipefail
+
+HOST=${HOST:-localhost:4713}
+ADMIN_PASS=${ADMIN_PASS:-adminpass}
+
+FAIL_COUNT=0
+TEST_COUNT=0
+
+CURL_BODY_FILE=$(mktemp -t amuleapi_07_read_stats_and_search_results_body.XXXXXX)
+trap 'rm -f "$CURL_BODY_FILE"' EXIT
+
+_die()  { echo "FATAL: $*" >&2; exit 2; }
+_pass() { TEST_COUNT=$((TEST_COUNT+1)); echo "  PASS  $1"; }
+_fail() {
+	TEST_COUNT=$((TEST_COUNT+1)); FAIL_COUNT=$((FAIL_COUNT+1))
+	echo "  FAIL  $1"
+	shift
+	for arg in "$@"; do echo "        $arg"; done
+}
+
+_curl() {
+	local resp
+	resp=$(curl -s --max-time 10 -o "$CURL_BODY_FILE" -w '%{http_code}' "$@") \
+		|| _die "curl invocation failed for $*"
+	CURL_STATUS=$resp
+	CURL_BODY=$(cat "$CURL_BODY_FILE")
+}
+
+_assert_status() {
+	local expected=$1 label=$2
+	if [ "$CURL_STATUS" = "$expected" ]; then
+		_pass "$label (HTTP $CURL_STATUS)"
+	else
+		_fail "$label" "expected HTTP $expected, got $CURL_STATUS" \
+			"body head: $(printf '%s' "$CURL_BODY" | head -c 200)"
+	fi
+}
+
+_assert_json_eq() {
+	local expr=$1 expected=$2 label=$3
+	local actual
+	actual=$(printf '%s' "$CURL_BODY" | jq -r "$expr" 2>/dev/null) \
+		|| _fail "$label" "body was not valid JSON" "body: $CURL_BODY"
+	if [ "$actual" = "$expected" ]; then
+		_pass "$label"
+	else
+		_fail "$label" "expected $expected, got $actual" "body: $CURL_BODY"
+	fi
+}
+
+if ! command -v jq >/dev/null 2>&1; then
+	_die "jq is required."
+fi
+if ! curl -s -o /dev/null --max-time 2 "$HOST/api/v0/version" 2>/dev/null; then
+	_die "amuleapi at $HOST is not reachable."
+fi
+
+echo "amuleapi 07-read-stats-and-search-results smoke @ $HOST"
+
+TOKEN=$(curl -s -X POST -H "Content-Type: application/json" \
+	-d "{\"password\":\"$ADMIN_PASS\"}" \
+	"$HOST/api/v0/auth/login?type=bearer" | jq -r .token)
+[ -n "$TOKEN" ] && [ "$TOKEN" != "null" ] || _die "login failed"
+
+# Wait for the refresher to populate the cache (3 new EC roundtrips
+# plus the existing tick, so the first full snapshot lands by tick 2).
+sleep 4
+
+# --- 1. Auth gate. -------------------------------------------------
+for ep in stats/tree stats/graphs/download search/results; do
+	_curl "$HOST/api/v0/$ep"
+	_assert_status 401 "GET /$ep (no creds) → 401"
+done
+
+# --- 2. /stats/tree shape. -----------------------------------------
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/stats/tree"
+_assert_status 200 "GET /stats/tree → 200"
+_assert_json_eq '.nodes | type'            array  '/stats/tree .nodes is array'
+# amuled's stats tree always has at least Uptime + Transfer + Connection
+# at the top level — assert a non-empty `nodes` and a labeled first
+# entry rather than pinning specific text (locale-dependent).
+_assert_json_eq '.nodes | length > 0'      true   '/stats/tree has at least one top-level node'
+_assert_json_eq '.nodes[0].label | type'   string '/stats/tree first node has a label'
+_assert_json_eq '.nodes[0].children | type' array '/stats/tree first node has a children array'
+
+# --- 3. /stats/graphs/{graph} — all four named graphs. -------------
+for g in download upload connections kad; do
+	_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/stats/graphs/$g"
+	_assert_status 200 "GET /stats/graphs/$g → 200"
+	_assert_json_eq '.graph'                    "$g"  "/stats/graphs/$g reports graph=$g"
+	_assert_json_eq '.interval_seconds | type'  number "/stats/graphs/$g interval_seconds is numeric"
+	_assert_json_eq '.points | type'            array  "/stats/graphs/$g .points is array"
+	_assert_json_eq '.session | type'           object "/stats/graphs/$g .session is object"
+done
+# Per-graph unit mapping.
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/stats/graphs/download"
+_assert_json_eq '.unit' bps   '/stats/graphs/download reports unit=bps'
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/stats/graphs/connections"
+_assert_json_eq '.unit' count '/stats/graphs/connections reports unit=count'
+
+# --- 4. /stats/graphs/{graph} ?width=N tailing. --------------------
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/stats/graphs/download?width=5"
+_assert_status 200 "GET /stats/graphs/download?width=5 → 200"
+_assert_json_eq '.points | length <= 5' true \
+	'/stats/graphs/download?width=5 returns ≤5 points'
+# When a point exists, it must carry both t (ISO-8601) and t_unix.
+if [ "$(printf '%s' "$CURL_BODY" | jq '.points | length')" -gt 0 ]; then
+	_assert_json_eq '.points[0].t | length' 20 \
+		'/stats/graphs/download point.t is 20-char ISO-8601'
+	_assert_json_eq '.points[0].t_unix | type' number \
+		'/stats/graphs/download point.t_unix is numeric'
+	_assert_json_eq '.points[0].value | type' number \
+		'/stats/graphs/download point.value is numeric'
+fi
+
+# --- 5. Unknown graph name → 404. ----------------------------------
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/stats/graphs/bogus"
+_assert_status 404 "GET /stats/graphs/bogus → 404"
+_assert_json_eq '.error.code' not_found \
+	'/stats/graphs/{unknown} carries error.code=not_found'
+
+# --- 6. /search/results — empty until Phase 5's POST /search. ------
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/search/results"
+_assert_status 200 "GET /search/results → 200"
+_assert_json_eq '.results | type'       array '/search/results .results is array'
+# Tolerant of empty results; if a phase 5 search was triggered earlier
+# and left state, the per-item shape still checks.
+COUNT=$(printf '%s' "$CURL_BODY" | jq '.results | length')
+if [ "$COUNT" -gt 0 ]; then
+	_assert_json_eq '.results[0].hash | length' 32 \
+		'/search/results[0].hash is 32-char hex'
+	_assert_json_eq '.results[0].name | type'   string \
+		'/search/results[0].name is string'
+	_assert_json_eq '.results[0].sources | type' object \
+		'/search/results[0].sources is object'
+fi
+
+# --- 7. Method gate. -----------------------------------------------
+for ep in stats/tree stats/graphs/download search/results; do
+	_curl -X DELETE -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/$ep"
+	_assert_status 405 "DELETE /api/v0/$ep → 405"
+done
+
+# --- Summary. -----------------------------------------------------
+echo
+if [ "$FAIL_COUNT" -eq 0 ]; then
+	echo "OK: $TEST_COUNT/$TEST_COUNT passed"
+	exit 0
+fi
+echo "FAIL: $FAIL_COUNT/$TEST_COUNT failed"
+exit 1
diff --git a/unittests/curl-tests/amuleapi/08-read-download-parts.sh b/unittests/curl-tests/amuleapi/08-read-download-parts.sh
new file mode 100755
index 0000000000..c673e8e7c1
--- /dev/null
+++ b/unittests/curl-tests/amuleapi/08-read-download-parts.sh
@@ -0,0 +1,239 @@
+#!/usr/bin/env bash
+#
+# amuleapi 08-read-download-parts — `progress.parts` on `GET /downloads/{hash}` detail.
+#
+# Validates the stateful RLE decoder pass that lands per-part state on
+# the bare-object detail response. The list endpoint (`GET /downloads`)
+# stays unchanged — `progress.parts` is detail-only since the array
+# scales O(file_size / PARTSIZE) and most clients listing the queue
+# don't want it (Q2 in PLAN §12 — no cap, omit-on-list).
+#
+# Wire contract:
+#   GET /downloads          → `progress: { percent: float }`
+#   GET /downloads/{hash}   → `progress: { percent: float,
+#                                          parts: [{state, sources}] }`
+#
+# `parts.length == ceil(size / 9728000)` (ed2k PARTSIZE).
+# `state` ∈ {"complete", "incomplete", "missing"}.
+# `sources` is uint16 (0 ≤ sources ≤ 65535).
+#
+# This script tolerates an empty download queue — every assertion past
+# the auth gate is conditionally skipped if no downloads are active.
+# Run it against a daemon with at least one live download for the
+# decoder-roundtrip checks to fire.
+
+set -u
+set -o pipefail
+
+HOST=${HOST:-localhost:4713}
+ADMIN_PASS=${ADMIN_PASS:-adminpass}
+
+FAIL_COUNT=0
+TEST_COUNT=0
+
+CURL_BODY_FILE=$(mktemp -t amuleapi_08_read_download_parts_body.XXXXXX)
+trap 'rm -f "$CURL_BODY_FILE"' EXIT
+
+_die()  { echo "FATAL: $*" >&2; exit 2; }
+_pass() { TEST_COUNT=$((TEST_COUNT+1)); echo "  PASS  $1"; }
+_fail() {
+	TEST_COUNT=$((TEST_COUNT+1)); FAIL_COUNT=$((FAIL_COUNT+1))
+	echo "  FAIL  $1"
+	shift
+	for arg in "$@"; do echo "        $arg"; done
+}
+
+_curl() {
+	local resp
+	resp=$(curl -s --max-time 10 -o "$CURL_BODY_FILE" -w '%{http_code}' "$@") \
+		|| _die "curl invocation failed for $*"
+	CURL_STATUS=$resp
+	CURL_BODY=$(cat "$CURL_BODY_FILE")
+}
+
+_assert_status() {
+	local expected=$1 label=$2
+	if [ "$CURL_STATUS" = "$expected" ]; then
+		_pass "$label (HTTP $CURL_STATUS)"
+	else
+		_fail "$label" "expected HTTP $expected, got $CURL_STATUS" \
+			"body head: $(printf '%s' "$CURL_BODY" | head -c 200)"
+	fi
+}
+
+_assert_json_eq() {
+	local expr=$1 expected=$2 label=$3
+	local actual
+	actual=$(printf '%s' "$CURL_BODY" | jq -r "$expr" 2>/dev/null) \
+		|| _fail "$label" "body was not valid JSON" "body: $CURL_BODY"
+	if [ "$actual" = "$expected" ]; then
+		_pass "$label"
+	else
+		_fail "$label" "expected $expected, got $actual" "body: $CURL_BODY"
+	fi
+}
+
+if ! command -v jq >/dev/null 2>&1; then
+	_die "jq is required."
+fi
+if ! curl -s -o /dev/null --max-time 2 "$HOST/api/v0/version" 2>/dev/null; then
+	_die "amuleapi at $HOST is not reachable."
+fi
+
+echo "amuleapi 08-read-download-parts smoke @ $HOST"
+
+TOKEN=$(curl -s -X POST -H "Content-Type: application/json" \
+	-d "{\"password\":\"$ADMIN_PASS\"}" \
+	"$HOST/api/v0/auth/login?type=bearer" | jq -r .token)
+[ -n "$TOKEN" ] && [ "$TOKEN" != "null" ] || _die "login failed"
+
+# Refresher needs at least 2 ticks for the two-phase INC protocol to
+# converge — Phase 1 (UPDATE) surfaces new ECIDs, Phase 2 (FULL) ships
+# identity + GAP/PART blobs. The stateful RLE decoder needs the FULL
+# pass to seed itself before any UPDATE tick can produce a usable
+# decode. Give it 4 s; matches 07-read-stats-and-search-results.sh.
+sleep 4
+
+# --- 1. List endpoint MUST NOT carry `progress.parts`. -------------
+#
+# Q2 + per-list-omit decision: `progress.parts` is detail-only. A list
+# of 1000 downloads × ~150 parts/file would be 150k objects in the
+# response; clients walk the list endpoint for queue state and the
+# detail endpoint when they need the per-part breakdown.
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/downloads"
+_assert_status 200 "GET /downloads → 200"
+_assert_json_eq '.downloads | type' array '/downloads .downloads is array'
+
+COUNT=$(printf '%s' "$CURL_BODY" | jq '.downloads | length')
+echo "    info: $COUNT downloads currently in queue"
+
+if [ "$COUNT" -gt 0 ]; then
+	# Pick the first download in the list and assert it does NOT carry
+	# `progress.parts` — even if the underlying snapshot has decoded
+	# arrays populated, the list emitter must omit them.
+	_assert_json_eq '.downloads[0].progress.parts // "absent"' absent \
+		'/downloads[0].progress.parts is absent (detail-only field)'
+	_assert_json_eq '.downloads[0].progress.percent | type' number \
+		'/downloads[0].progress.percent is numeric'
+
+	# Pull the first hash for the detail-endpoint pass below.
+	FIRST_HASH=$(printf '%s' "$CURL_BODY" | jq -r '.downloads[0].hash')
+	FIRST_SIZE=$(printf '%s' "$CURL_BODY" | jq -r '.downloads[0].size')
+
+	# --- 2. Detail endpoint carries `progress.parts`. --------------
+	_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/downloads/$FIRST_HASH"
+	_assert_status 200 "GET /downloads/{hash} → 200"
+	_assert_json_eq '.hash'                  "$FIRST_HASH" \
+		'/downloads/{hash} echoes hash (bare object, not enveloped)'
+	_assert_json_eq '.progress.parts | type' array \
+		'/downloads/{hash}.progress.parts is array'
+	_assert_json_eq '.progress.percent | type' number \
+		'/downloads/{hash}.progress.percent is numeric'
+
+	PARTS_LEN=$(printf '%s' "$CURL_BODY" | jq '.progress.parts | length')
+
+	# --- 3. parts.length == ceil(size / 9728000). ------------------
+	#
+	# PARTSIZE = 9728000 bytes (ed2k spec, frozen for protocol
+	# compatibility). The decoded_part_sources vector is sized to
+	# ceil(size / PARTSIZE); the gap-derived state array follows the
+	# same shape. If FIRST_SIZE is 0 we accept parts==0 (decoder
+	# legitimately has nothing to size against).
+	if [ "$FIRST_SIZE" -gt 0 ]; then
+		EXPECTED_PARTS=$(( (FIRST_SIZE + 9728000 - 1) / 9728000 ))
+		if [ "$PARTS_LEN" = "$EXPECTED_PARTS" ]; then
+			_pass "/downloads/{hash}.progress.parts.length == ceil(size/PARTSIZE) ($PARTS_LEN)"
+		elif [ "$PARTS_LEN" = "0" ]; then
+			# RLE decoder hasn't seen a full tick yet for this file — the
+			# detail handler still emits the array shape but the underlying
+			# decoded_part_sources vector is empty. This is a transient
+			# warmup state, not a failure: the second tick fills it in.
+			_pass "/downloads/{hash}.progress.parts.length == 0 (decoder warming up; expected on first tick)"
+		else
+			_fail "/downloads/{hash}.progress.parts.length sanity" \
+				"size=$FIRST_SIZE → expected $EXPECTED_PARTS, got $PARTS_LEN"
+		fi
+	fi
+
+	# --- 4. Per-part shape: {state, sources}. ----------------------
+	if [ "$PARTS_LEN" -gt 0 ]; then
+		_assert_json_eq '.progress.parts[0].state | type' string \
+			'/downloads/{hash}.progress.parts[0].state is string'
+		_assert_json_eq '.progress.parts[0].sources | type' number \
+			'/downloads/{hash}.progress.parts[0].sources is number'
+
+		# --- 5. state enum allowlist. ------------------------------
+		# Every part state must be one of {complete, incomplete, missing}.
+		# The walker is: has_gap → (sources>0 ? incomplete : missing);
+		# !has_gap → complete. Any other string means the emitter
+		# silently regressed.
+		BOGUS_COUNT=$(printf '%s' "$CURL_BODY" | jq \
+			'[.progress.parts[].state | select(. != "complete" and . != "incomplete" and . != "missing")] | length')
+		if [ "$BOGUS_COUNT" = "0" ]; then
+			_pass "/downloads/{hash} all part.state values ∈ {complete, incomplete, missing}"
+		else
+			_fail "/downloads/{hash} part.state enum" \
+				"$BOGUS_COUNT parts have an out-of-enum state value"
+		fi
+
+		# --- 6. sources is a uint16 (0 ≤ sources ≤ 65535). -------
+		OUT_OF_RANGE=$(printf '%s' "$CURL_BODY" | jq \
+			'[.progress.parts[].sources | select(. < 0 or . > 65535)] | length')
+		if [ "$OUT_OF_RANGE" = "0" ]; then
+			_pass "/downloads/{hash} all part.sources values fit in uint16"
+		else
+			_fail "/downloads/{hash} part.sources range" \
+				"$OUT_OF_RANGE parts have sources outside [0,65535]"
+		fi
+
+		# --- 7. Live downloading file has at least one non-complete
+		# part. A file in `downloading` status by definition has work
+		# remaining; if every part comes back `complete` the decoder
+		# either ran on a finished file or the gap-list parse is
+		# silently dropping every entry. Skip if the file is paused /
+		# completed / hashing.
+		STATUS=$(printf '%s' "$CURL_BODY" | jq -r '.status')
+		if [ "$STATUS" = "downloading" ]; then
+			NONCOMPLETE=$(printf '%s' "$CURL_BODY" | jq \
+				'[.progress.parts[].state | select(. != "complete")] | length')
+			if [ "$NONCOMPLETE" -gt 0 ]; then
+				_pass "/downloads/{hash} downloading file has $NONCOMPLETE non-complete parts (decoder live)"
+			else
+				_fail "/downloads/{hash} live-decoder sanity" \
+					"status=downloading but 0 non-complete parts in the gap-derived map" \
+					"size=$FIRST_SIZE percent=$(printf '%s' "$CURL_BODY" | jq '.progress.percent')"
+			fi
+		else
+			echo "    info: download status=$STATUS, skipping live-decoder non-complete-parts check"
+		fi
+	else
+		echo "    info: parts array empty (decoder warming up or file size=0); per-part shape checks skipped"
+	fi
+
+	# --- 8. URL hash case-insensitive (already covered in 4b but
+	# the detail endpoint changed shape so re-pin). ---------------
+	UPPER_HASH=$(echo "$FIRST_HASH" | tr 'a-f' 'A-F')
+	_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/downloads/$UPPER_HASH"
+	_assert_status 200 "GET /downloads/{HASH} (uppercase) → 200"
+	_assert_json_eq '.progress.parts | type' array \
+		'/downloads/{HASH} uppercase still carries progress.parts'
+else
+	echo "    info: no active downloads; the per-part shape checks need a live download"
+	echo "    info: passing the auth-gate + list-shape sweep only — run again with a downloading file for full coverage"
+fi
+
+# --- 9. 404 on unknown hash. ---------------------------------------
+_curl -H "Authorization: Bearer $TOKEN" \
+	"$HOST/api/v0/downloads/00000000000000000000000000000000"
+_assert_status 404 "GET /downloads/{nonexistent} → 404"
+_assert_json_eq '.error.code' not_found \
+	'/downloads/{nonexistent} carries error.code=not_found'
+
+# --- Summary. -----------------------------------------------------
+echo
+if [ "$FAIL_COUNT" -eq 0 ]; then
+	echo "OK: $TEST_COUNT/$TEST_COUNT passed"
+	exit 0
+fi
+echo "FAIL: $FAIL_COUNT/$TEST_COUNT failed"
+exit 1
diff --git a/unittests/curl-tests/amuleapi/09-refresher-consolidation.sh b/unittests/curl-tests/amuleapi/09-refresher-consolidation.sh
new file mode 100755
index 0000000000..7a57f25aa2
--- /dev/null
+++ b/unittests/curl-tests/amuleapi/09-refresher-consolidation.sh
@@ -0,0 +1,218 @@
+#!/usr/bin/env bash
+#
+# amuleapi 09-refresher-consolidation — EC_OP_GET_UPDATE @ EC_DETAIL_INC_UPDATE
+# refresher consolidation.
+#
+# Drops the per-substruct GET_DLOAD_QUEUE / GET_SHARED_FILES /
+# GET_SERVER_LIST polling path (each with its own two-phase UPDATE/
+# FULL split) in favour of a single GET_UPDATE roundtrip. /uploads
+# stays on GET_ULOAD_QUEUE (wire-semantic preservation — the
+# GET_UPDATE clients block is filtered server-side by the global
+# `TransmitOnlyUploadingClients` pref).
+#
+# This smoke is a wire-contract regression check: every field the
+# Phase 4b/4c smokes asserted on must STILL be present after the
+# refresher swap. progress.parts on the detail endpoint (Phase 4e)
+# must STILL show the RLE-decoded per-part state — proving the
+# stateful decoder still gets its baseline frame from GET_UPDATE's
+# INC_UPDATE-level payload.
+#
+# Net effect on ops/tick (steady state, no new ECIDs):
+#   * before: 10 ops (STAT_REQ, GET_DLOAD_QUEUE, GET_ULOAD_QUEUE,
+#                     GET_SHARED_FILES, GET_SERVER_LIST,
+#                     GET_PREFERENCES, GET_SERVERINFO, GET_STATSTREE,
+#                     GET_STATSGRAPHS, SEARCH_RESULTS)
+#   * after:   8 ops (GET_UPDATE replaces 3 of them, GET_ULOAD_QUEUE
+#                     stays for uploads, rest unchanged)
+#
+# On a cold tick the savings are larger (no Phase 2 FULL roundtrip
+# for new ECIDs in downloads/shared — INC_UPDATE ships identity in
+# the first response).
+
+set -u
+set -o pipefail
+
+HOST=${HOST:-localhost:4713}
+ADMIN_PASS=${ADMIN_PASS:-adminpass}
+
+FAIL_COUNT=0
+TEST_COUNT=0
+
+CURL_BODY_FILE=$(mktemp -t amuleapi_09_refresher_consolidation_body.XXXXXX)
+trap 'rm -f "$CURL_BODY_FILE"' EXIT
+
+_die()  { echo "FATAL: $*" >&2; exit 2; }
+_pass() { TEST_COUNT=$((TEST_COUNT+1)); echo "  PASS  $1"; }
+_fail() {
+	TEST_COUNT=$((TEST_COUNT+1)); FAIL_COUNT=$((FAIL_COUNT+1))
+	echo "  FAIL  $1"
+	shift
+	for arg in "$@"; do echo "        $arg"; done
+}
+
+_curl() {
+	local resp
+	resp=$(curl -s --max-time 10 -o "$CURL_BODY_FILE" -w '%{http_code}' "$@") \
+		|| _die "curl invocation failed for $*"
+	CURL_STATUS=$resp
+	CURL_BODY=$(cat "$CURL_BODY_FILE")
+}
+
+_assert_status() {
+	local expected=$1 label=$2
+	if [ "$CURL_STATUS" = "$expected" ]; then
+		_pass "$label (HTTP $CURL_STATUS)"
+	else
+		_fail "$label" "expected HTTP $expected, got $CURL_STATUS" \
+			"body head: $(printf '%s' "$CURL_BODY" | head -c 200)"
+	fi
+}
+
+_assert_json_eq() {
+	local expr=$1 expected=$2 label=$3
+	local actual
+	actual=$(printf '%s' "$CURL_BODY" | jq -r "$expr" 2>/dev/null) \
+		|| _fail "$label" "body was not valid JSON" "body: $CURL_BODY"
+	if [ "$actual" = "$expected" ]; then
+		_pass "$label"
+	else
+		_fail "$label" "expected $expected, got $actual" "body: $CURL_BODY"
+	fi
+}
+
+if ! command -v jq >/dev/null 2>&1; then
+	_die "jq is required."
+fi
+if ! curl -s -o /dev/null --max-time 2 "$HOST/api/v0/version" 2>/dev/null; then
+	_die "amuleapi at $HOST is not reachable."
+fi
+
+echo "amuleapi 09-refresher-consolidation smoke @ $HOST"
+
+TOKEN=$(curl -s -X POST -H "Content-Type: application/json" \
+	-d "{\"password\":\"$ADMIN_PASS\"}" \
+	"$HOST/api/v0/auth/login?type=bearer" | jq -r .token)
+[ -n "$TOKEN" ] && [ "$TOKEN" != "null" ] || _die "login failed"
+
+# Let the refresher complete at least one full tick after auth so the
+# GET_UPDATE-populated caches are warm. INC_UPDATE on cold start
+# delivers a larger payload (every file shipped with full identity)
+# than steady-state ticks, but the response shape is unchanged.
+sleep 4
+
+# --- 1. /downloads — list endpoint shape preserved. ----------------
+#
+# Phase 4b asserted these field types on the list shape; if GET_UPDATE
+# dispatch broke any of them, the wire contract is broken.
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/downloads"
+_assert_status 200 "GET /downloads → 200"
+_assert_json_eq '.downloads | type'     array '/downloads .downloads is array'
+
+DCOUNT=$(printf '%s' "$CURL_BODY" | jq '.downloads | length')
+echo "    info: $DCOUNT downloads in queue (populated via GET_UPDATE)"
+
+if [ "$DCOUNT" -gt 0 ]; then
+	# Identity arrives in the same tick at INC_UPDATE — no second
+	# roundtrip needed. A field empty here means the walker isn't
+	# picking up the identity tags that EC_DETAIL_INC_UPDATE ships.
+	_assert_json_eq '.downloads[0].hash | length' 32 \
+		'/downloads[0].hash is 32-char hex (identity from one tick)'
+	_assert_json_eq '.downloads[0].name | type'   string \
+		'/downloads[0].name is non-null string'
+	_assert_json_eq '.downloads[0].size | type'   number \
+		'/downloads[0].size is numeric'
+	_assert_json_eq '.downloads[0].status | type' string \
+		'/downloads[0].status is string'
+	_assert_json_eq '.downloads[0].priority | type' string \
+		'/downloads[0].priority is string'
+	# Source counts come through the merge path — sanity check the
+	# `sources` substruct still populates.
+	_assert_json_eq '.downloads[0].sources | type' object \
+		'/downloads[0].sources is object'
+
+	FIRST_HASH=$(printf '%s' "$CURL_BODY" | jq -r '.downloads[0].hash')
+
+	# --- 2. /downloads/{hash} detail — progress.parts still ships. -
+	#
+	# Phase 4e relies on the stateful RLE decoder. GET_UPDATE at
+	# INC_UPDATE ships the GAP/PART blobs (via the encoder's Encode
+	# call at ExternalConn.cpp:942) so the decoder gets its frames.
+	# If the consolidation broke the RLE wiring, parts would come back
+	# empty or with the wrong length.
+	_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/downloads/$FIRST_HASH"
+	_assert_status 200 "GET /downloads/{hash} → 200"
+	_assert_json_eq '.progress.parts | type' array \
+		'/downloads/{hash}.progress.parts is array (RLE decoder still wired)'
+fi
+
+# --- 3. /shared — list endpoint shape preserved. -------------------
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/shared"
+_assert_status 200 "GET /shared → 200"
+_assert_json_eq '.shared | type'        array '/shared .shared is array'
+
+SCOUNT=$(printf '%s' "$CURL_BODY" | jq '.shared | length')
+echo "    info: $SCOUNT shared files (populated via GET_UPDATE KNOWNFILE dispatch)"
+
+if [ "$SCOUNT" -gt 0 ]; then
+	_assert_json_eq '.shared[0].hash | length' 32 \
+		'/shared[0].hash is 32-char hex'
+	_assert_json_eq '.shared[0].name | type'   string \
+		'/shared[0].name is string'
+	_assert_json_eq '.shared[0].size | type'   number \
+		'/shared[0].size is numeric'
+	_assert_json_eq '.shared[0].priority | type' string \
+		'/shared[0].priority is string'
+fi
+
+# --- 4. /servers — list endpoint shape preserved. ------------------
+#
+# Now populated by walking the EC_TAG_SERVER container inside the
+# GET_UPDATE response (one level deeper than the legacy GET_SERVER_LIST
+# response, where servers were top-level).
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/servers"
+_assert_status 200 "GET /servers → 200"
+_assert_json_eq '.servers | type'       array '/servers .servers is array'
+
+NSERV=$(printf '%s' "$CURL_BODY" | jq '.servers | length')
+echo "    info: $NSERV servers configured (populated via GET_UPDATE container walk)"
+
+if [ "$NSERV" -gt 0 ]; then
+	# Identity preserved through the container walk — name, address,
+	# user counts. The MergeServerTag is_new branch fires for fresh
+	# servers; on subsequent ticks the CValueMap suppresses unchanged
+	# fields and the !is_new branch keeps the cached value.
+	_assert_json_eq '.servers[0].name | type'     string \
+		'/servers[0].name is string'
+	_assert_json_eq '.servers[0].address | type'  string \
+		'/servers[0].address is string'
+	_assert_json_eq '.servers[0].priority | type' string \
+		'/servers[0].priority is string'
+fi
+
+# --- 5. /uploads — endpoint retired in Phase 4g. -------------------
+#
+# /clients now covers the full peer surface (every upload_state,
+# including queue waiters and download-side peers). Consumers filter
+# client-side by upload_state == "uploading" when they want the
+# legacy /uploads view. 10-refresher-lazy-ondemand.sh exercises the new shape.
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/uploads"
+_assert_status 404 "GET /uploads → 404 (retired in Phase 4g)"
+
+# --- 6. /status, /kad, /preferences — unaffected by the consolidation
+# (they ride on STAT_REQ and GET_PREFERENCES, which we did not touch).
+# A sanity glance to catch unrelated regressions slipping in.
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/status"
+_assert_status 200 "GET /status → 200 (unaffected by Phase 4f)"
+_assert_json_eq '.ed2k.state | type' string '/status.ed2k.state still populated'
+
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/kad"
+_assert_status 200 "GET /kad → 200 (unaffected by Phase 4f)"
+
+# --- Summary. -----------------------------------------------------
+echo
+if [ "$FAIL_COUNT" -eq 0 ]; then
+	echo "OK: $TEST_COUNT/$TEST_COUNT passed"
+	exit 0
+fi
+echo "FAIL: $FAIL_COUNT/$TEST_COUNT failed"
+exit 1
diff --git a/unittests/curl-tests/amuleapi/10-refresher-lazy-ondemand.sh b/unittests/curl-tests/amuleapi/10-refresher-lazy-ondemand.sh
new file mode 100755
index 0000000000..5ab6cbaaa6
--- /dev/null
+++ b/unittests/curl-tests/amuleapi/10-refresher-lazy-ondemand.sh
@@ -0,0 +1,231 @@
+#!/usr/bin/env bash
+#
+# amuleapi 10-refresher-lazy-ondemand — refresher slim-down: GET_ULOAD_QUEUE folded
+# into GET_UPDATE, four lazy ops moved to on-demand TTL-cached fetch.
+#
+# Per-tick EC ops dropped from 8 to 3:
+#   1. EC_OP_STAT_REQ @ EC_DETAIL_FULL     → /status + /kad + /logs/amule
+#   2. EC_OP_GET_UPDATE @ EC_DETAIL_INC_UPDATE → /downloads + /shared +
+#                                              /servers + /clients
+#   3. EC_OP_GET_PREFERENCES                → /preferences + /categories
+#
+# Four endpoints lazy-fetched on first GET, coalesced via 1 s TTL:
+#   * /logs/serverinfo  (EC_OP_GET_SERVERINFO)
+#   * /stats/tree       (EC_OP_GET_STATSTREE)
+#   * /stats/graphs/{X} (EC_OP_GET_STATSGRAPHS — one fetch serves all 4)
+#   * /search/results   (EC_OP_SEARCH_RESULTS)
+#
+# Wire changes:
+#   * /uploads RETIRED → /clients is the unified peer surface
+#   * /clients ships every alive peer (upload + download + queue +
+#     idle), with role-decoded state strings
+#   * lazy endpoints' `snapshot_at` reflects per-endpoint fetch time
+#     (not the refresher tick boundary)
+
+set -u
+set -o pipefail
+
+HOST=${HOST:-localhost:4713}
+ADMIN_PASS=${ADMIN_PASS:-adminpass}
+
+FAIL_COUNT=0
+TEST_COUNT=0
+
+CURL_BODY_FILE=$(mktemp -t amuleapi_10_refresher_lazy_ondemand_body.XXXXXX)
+trap 'rm -f "$CURL_BODY_FILE"' EXIT
+
+_die()  { echo "FATAL: $*" >&2; exit 2; }
+_pass() { TEST_COUNT=$((TEST_COUNT+1)); echo "  PASS  $1"; }
+_fail() {
+	TEST_COUNT=$((TEST_COUNT+1)); FAIL_COUNT=$((FAIL_COUNT+1))
+	echo "  FAIL  $1"
+	shift
+	for arg in "$@"; do echo "        $arg"; done
+}
+
+_curl() {
+	local resp
+	resp=$(curl -s --max-time 10 -o "$CURL_BODY_FILE" -w '%{http_code}' "$@") \
+		|| _die "curl invocation failed for $*"
+	CURL_STATUS=$resp
+	CURL_BODY=$(cat "$CURL_BODY_FILE")
+}
+
+_assert_status() {
+	local expected=$1 label=$2
+	if [ "$CURL_STATUS" = "$expected" ]; then
+		_pass "$label (HTTP $CURL_STATUS)"
+	else
+		_fail "$label" "expected HTTP $expected, got $CURL_STATUS" \
+			"body head: $(printf '%s' "$CURL_BODY" | head -c 200)"
+	fi
+}
+
+_assert_json_eq() {
+	local expr=$1 expected=$2 label=$3
+	local actual
+	actual=$(printf '%s' "$CURL_BODY" | jq -r "$expr" 2>/dev/null) \
+		|| _fail "$label" "body was not valid JSON" "body: $CURL_BODY"
+	if [ "$actual" = "$expected" ]; then
+		_pass "$label"
+	else
+		_fail "$label" "expected $expected, got $actual" "body: $CURL_BODY"
+	fi
+}
+
+if ! command -v jq >/dev/null 2>&1; then
+	_die "jq is required."
+fi
+if ! curl -s -o /dev/null --max-time 2 "$HOST/api/v0/version" 2>/dev/null; then
+	_die "amuleapi at $HOST is not reachable."
+fi
+
+echo "amuleapi 10-refresher-lazy-ondemand smoke @ $HOST"
+
+TOKEN=$(curl -s -X POST -H "Content-Type: application/json" \
+	-d "{\"password\":\"$ADMIN_PASS\"}" \
+	"$HOST/api/v0/auth/login?type=bearer" | jq -r .token)
+[ -n "$TOKEN" ] && [ "$TOKEN" != "null" ] || _die "login failed"
+
+# Refresher has 3 ops/tick now (STAT_REQ + GET_UPDATE + PREFERENCES).
+# The first tick still needs ~1 s; sleep 4 covers it comfortably.
+sleep 4
+
+# --- 1. /uploads RETIRED → 404. ------------------------------------
+#
+# The legacy endpoint is gone; /clients replaces it with role-decoded
+# state for every peer (upload + download + queue + idle). Consumers
+# wanting the legacy view filter client-side by upload_state ==
+# "uploading".
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/uploads"
+_assert_status 404 "GET /uploads → 404 (endpoint retired)"
+
+# --- 2. /clients shape. --------------------------------------------
+#
+# Phase 4g unified peer surface. Every alive peer in
+# theApp->clientlist surfaces, populated from the EC_TAG_CLIENT
+# container inside the GET_UPDATE response.
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/clients"
+_assert_status 200 "GET /clients → 200"
+_assert_json_eq '.clients | type'        array '/clients .clients is array'
+
+CCOUNT=$(printf '%s' "$CURL_BODY" | jq '.clients | length')
+echo "    info: $CCOUNT peers cached (populated via GET_UPDATE CLIENT subtree)"
+
+if [ "$CCOUNT" -gt 0 ]; then
+	# Per-peer shape. The state enums are wire strings (decoded
+	# server-side from US_* / DS_* / IS_* / SO_* / OBST_* codes).
+	_assert_json_eq '.clients[0].client_ecid | type'    number   '/clients[0].client_ecid is numeric'
+	_assert_json_eq '.clients[0].user_hash | length'    32       '/clients[0].user_hash is 32-char hex'
+	_assert_json_eq '.clients[0].upload_state | type'   string   '/clients[0].upload_state is string'
+	_assert_json_eq '.clients[0].download_state | type' string   '/clients[0].download_state is string'
+	_assert_json_eq '.clients[0].ident_state | type'    string   '/clients[0].ident_state is string'
+	_assert_json_eq '.clients[0].software | type'       string   '/clients[0].software is string'
+	_assert_json_eq '.clients[0].xfer | type'           object   '/clients[0].xfer is object'
+	_assert_json_eq '.clients[0].xfer.up_session | type'   number '/clients[0].xfer.up_session is numeric'
+	_assert_json_eq '.clients[0].xfer.down_session | type' number '/clients[0].xfer.down_session is numeric'
+
+	# State enum allowlists — any peer's upload_state must be one of
+	# the wire strings the walker emits. Catch silent regressions if
+	# the enum decoder gets a new US_* value without a mapping.
+	BOGUS_US=$(printf '%s' "$CURL_BODY" | jq \
+		'[.clients[].upload_state | select(. != "uploading" and . != "queued" and . != "waitcallback" and . != "connecting" and . != "pending" and . != "lowtolowip" and . != "banned" and . != "error" and . != "idle" and . != "unknown")] | length')
+	if [ "$BOGUS_US" = "0" ]; then
+		_pass "/clients upload_state values are all from the US_* enum mapping"
+	else
+		_fail "/clients upload_state enum allowlist" \
+			"$BOGUS_US peers have an out-of-enum upload_state"
+	fi
+
+	BOGUS_DS=$(printf '%s' "$CURL_BODY" | jq \
+		'[.clients[].download_state | select(. != "downloading" and . != "onqueue" and . != "connected" and . != "connecting" and . != "waitcallback" and . != "waitcallbackkad" and . != "reqhashset" and . != "noneededparts" and . != "toomanyconns" and . != "toomanyconnskad" and . != "lowtolowip" and . != "banned" and . != "error" and . != "idle" and . != "remotequeuefull" and . != "unknown")] | length')
+	if [ "$BOGUS_DS" = "0" ]; then
+		_pass "/clients download_state values are all from the DS_* enum mapping"
+	else
+		_fail "/clients download_state enum allowlist" \
+			"$BOGUS_DS peers have an out-of-enum download_state"
+	fi
+fi
+
+# --- 3. Lazy-fetch endpoints — fresh per-endpoint snapshot_at. -----
+#
+# Per Phase 4g, /stats/tree, /stats/graphs/{X}, /search/results, and
+# /logs/serverinfo no longer ride the refresher tick. Each handler
+# drives its own EC roundtrip on first call, coalesced via 1 s TTL.
+# The `snapshot_at` field on each reflects the per-endpoint fetch
+# time, not the refresher tick.
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/stats/tree"
+_assert_status 200 "GET /stats/tree → 200 (lazy fetch)"
+_assert_json_eq '.nodes | type'        array '/stats/tree .nodes is array'
+
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/stats/graphs/download"
+_assert_status 200 "GET /stats/graphs/download → 200 (lazy fetch)"
+_assert_json_eq '.graph' download         '/stats/graphs/download reports graph=download'
+_assert_json_eq '.unit' bps               '/stats/graphs/download reports unit=bps'
+_assert_json_eq '.points | type' array    '/stats/graphs/download .points is array'
+
+# TTL coalescing — two same-endpoint GETs within the 1 s window must
+# share the cached backing fetch. Observable via ETag (Phase 7): same
+# cached body bytes → same ETag. The per-point timestamps inside
+# /stats/graphs are anchored to the cache's `fetched_at`, so they
+# stay constant within a cache window; only between fetches do they
+# advance.
+GRAPH_ETAG_1=$(curl -s -I -H "Authorization: Bearer $TOKEN" \
+	"$HOST/api/v0/stats/graphs/download" \
+	| sed -n 's/^[Ee][Tt][Aa][Gg]:[[:space:]]*\([^[:cntrl:]]*\).*/\1/p' | head -1)
+GRAPH_ETAG_2=$(curl -s -I -H "Authorization: Bearer $TOKEN" \
+	"$HOST/api/v0/stats/graphs/download" \
+	| sed -n 's/^[Ee][Tt][Aa][Gg]:[[:space:]]*\([^[:cntrl:]]*\).*/\1/p' | head -1)
+if [ "$GRAPH_ETAG_1" = "$GRAPH_ETAG_2" ] && [ -n "$GRAPH_ETAG_1" ]; then
+	_pass "/stats/graphs/download back-to-back share the same fetch (1 s TTL coalescing; ETag stable: $GRAPH_ETAG_1)"
+else
+	_fail "/stats/graphs TTL coalescing" \
+		"first ETag=$GRAPH_ETAG_1, second=$GRAPH_ETAG_2 — expected identical within the 1 s window"
+fi
+
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/stats/graphs/bogus"
+_assert_status 404 "GET /stats/graphs/bogus → 404 (still validated)"
+
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/search/results"
+_assert_status 200 "GET /search/results → 200 (lazy fetch)"
+_assert_json_eq '.results | type' array '/search/results .results is array'
+
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/logs/serverinfo"
+_assert_status 200 "GET /logs/serverinfo → 200 (lazy fetch)"
+_assert_json_eq '.text | type' string '/logs/serverinfo .text is string'
+_assert_json_eq '.total_bytes | type' number '/logs/serverinfo .total_bytes is numeric'
+
+# --- 4. Per-tick endpoints still fresh from the refresher. ---------
+#
+# Sanity check the trio that stays on the refresher path —
+# downloads / shared / servers / clients / status / kad — they all
+# pull `snapshot_at` from CState::SnapshotAt which marks tick
+# completion.
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/status"
+_assert_status 200 "GET /status → 200 (still per-tick)"
+_assert_json_eq '.ed2k.state | type' string '/status.ed2k.state populated'
+
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/downloads"
+_assert_status 200 "GET /downloads → 200 (still per-tick)"
+_assert_json_eq '.downloads | type' array '/downloads .downloads is array'
+
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/shared"
+_assert_status 200 "GET /shared → 200 (still per-tick)"
+_assert_json_eq '.shared | type' array '/shared .shared is array'
+
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/servers"
+_assert_status 200 "GET /servers → 200 (still per-tick)"
+_assert_json_eq '.servers | type' array '/servers .servers is array'
+
+# --- 5. Method gate on /clients. -----------------------------------
+_curl -X DELETE -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/clients"
+_assert_status 405 "DELETE /clients → 405"
+
+# --- Summary. -----------------------------------------------------
+echo
+if [ "$FAIL_COUNT" -eq 0 ]; then
+	echo "OK: $TEST_COUNT/$TEST_COUNT passed"
+	exit 0
+fi
+echo "FAIL: $FAIL_COUNT/$TEST_COUNT failed"
+exit 1
diff --git a/unittests/curl-tests/amuleapi/11-downloads-default-filter.sh b/unittests/curl-tests/amuleapi/11-downloads-default-filter.sh
new file mode 100755
index 0000000000..ac4607c1d8
--- /dev/null
+++ b/unittests/curl-tests/amuleapi/11-downloads-default-filter.sh
@@ -0,0 +1,196 @@
+#!/usr/bin/env bash
+#
+# amuleapi 11-downloads-default-filter — /downloads default-filter completed + status
+# decode fix.
+#
+# Two related changes:
+#   1. DownloadStatusName at PS_COMPLETE / PS_COMPLETING short-circuits
+#      BEFORE the `stopped` check. amuled holds finished downloads in
+#      `m_completedDownloads` with EC_TAG_PARTFILE_STOPPED set true;
+#      the old decoder reported "paused" for them, masking the
+#      completion state. Fix exposes the "completed" wire string the
+#      schema documented.
+#   2. /downloads list filters status=="completed" entries by default.
+#      `m_completedDownloads` is amuled's own awaiting-clear list;
+#      surfacing those alongside the active queue confuses consumers.
+#      Opt back in with `?include_completed=1`.
+#      The detail endpoint (`GET /downloads/{hash}`) is UNCHANGED —
+#      a consumer asking for a specific file by hash gets it
+#      regardless of its status.
+#
+# Phase 5b exercises the clear-completed mutations:
+#   `POST /downloads/clear_completed`              (bulk-clear, no body)
+#   `POST /downloads/clear_completed {"hash":...}` (single-entry clear)
+# Both wire to EC_OP_CLEAR_COMPLETED. `DELETE /downloads/{hash}` is
+# active-only and 409s on completed entries — see 13-downloads-delete-clear for the
+# 409 + per-entry clear assertions.
+
+set -u
+set -o pipefail
+
+HOST=${HOST:-localhost:4713}
+ADMIN_PASS=${ADMIN_PASS:-adminpass}
+
+FAIL_COUNT=0
+TEST_COUNT=0
+
+CURL_BODY_FILE=$(mktemp -t amuleapi_11_downloads_default_filter_body.XXXXXX)
+trap 'rm -f "$CURL_BODY_FILE"' EXIT
+
+_die()  { echo "FATAL: $*" >&2; exit 2; }
+_pass() { TEST_COUNT=$((TEST_COUNT+1)); echo "  PASS  $1"; }
+_fail() {
+	TEST_COUNT=$((TEST_COUNT+1)); FAIL_COUNT=$((FAIL_COUNT+1))
+	echo "  FAIL  $1"
+	shift
+	for arg in "$@"; do echo "        $arg"; done
+}
+
+_curl() {
+	local resp
+	resp=$(curl -s --max-time 10 -o "$CURL_BODY_FILE" -w '%{http_code}' "$@") \
+		|| _die "curl invocation failed for $*"
+	CURL_STATUS=$resp
+	CURL_BODY=$(cat "$CURL_BODY_FILE")
+}
+
+_assert_status() {
+	local expected=$1 label=$2
+	if [ "$CURL_STATUS" = "$expected" ]; then
+		_pass "$label (HTTP $CURL_STATUS)"
+	else
+		_fail "$label" "expected HTTP $expected, got $CURL_STATUS" \
+			"body head: $(printf '%s' "$CURL_BODY" | head -c 200)"
+	fi
+}
+
+_assert_json_eq() {
+	local expr=$1 expected=$2 label=$3
+	local actual
+	actual=$(printf '%s' "$CURL_BODY" | jq -r "$expr" 2>/dev/null) \
+		|| _fail "$label" "body was not valid JSON" "body: $CURL_BODY"
+	if [ "$actual" = "$expected" ]; then
+		_pass "$label"
+	else
+		_fail "$label" "expected $expected, got $actual" "body: $CURL_BODY"
+	fi
+}
+
+if ! command -v jq >/dev/null 2>&1; then
+	_die "jq is required."
+fi
+if ! curl -s -o /dev/null --max-time 2 "$HOST/api/v0/version" 2>/dev/null; then
+	_die "amuleapi at $HOST is not reachable."
+fi
+
+echo "amuleapi 11-downloads-default-filter smoke @ $HOST"
+
+TOKEN=$(curl -s -X POST -H "Content-Type: application/json" \
+	-d "{\"password\":\"$ADMIN_PASS\"}" \
+	"$HOST/api/v0/auth/login?type=bearer" | jq -r .token)
+[ -n "$TOKEN" ] && [ "$TOKEN" != "null" ] || _die "login failed"
+sleep 4
+
+# --- 1. Default /downloads — completed entries filtered out. ------
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/downloads"
+_assert_status 200 "GET /downloads → 200"
+_assert_json_eq '.downloads | type' array '/downloads .downloads is array'
+
+# By definition: no entry in the default response should carry
+# status == "completed". This is the contract; smoke pins it
+# regardless of the daemon's current download mix.
+BOGUS=$(printf '%s' "$CURL_BODY" | jq '[.downloads[].status | select(. == "completed")] | length')
+if [ "$BOGUS" = "0" ]; then
+	_pass "/downloads default has zero status==\"completed\" entries (filter active)"
+else
+	_fail "/downloads default filter" \
+		"$BOGUS entries with status==completed leaked through the default filter"
+fi
+
+DEFAULT_COUNT=$(printf '%s' "$CURL_BODY" | jq '.downloads | length')
+echo "    info: /downloads default returned $DEFAULT_COUNT entries (completed filtered)"
+
+# --- 2. ?include_completed=1 opt-in. ------------------------------
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/downloads?include_completed=1"
+_assert_status 200 "GET /downloads?include_completed=1 → 200"
+_assert_json_eq '.downloads | type' array '/downloads?include_completed=1 .downloads is array'
+
+OPT_IN_COUNT=$(printf '%s' "$CURL_BODY" | jq '.downloads | length')
+echo "    info: /downloads?include_completed=1 returned $OPT_IN_COUNT entries"
+
+# The opt-in count must be >= the default count (filter is strictly
+# additive on the opt-in path).
+if [ "$OPT_IN_COUNT" -ge "$DEFAULT_COUNT" ]; then
+	_pass "?include_completed=1 returns >= default count ($OPT_IN_COUNT >= $DEFAULT_COUNT)"
+else
+	_fail "?include_completed=1 cardinality" \
+		"opt-in count $OPT_IN_COUNT < default count $DEFAULT_COUNT — filter regression"
+fi
+
+# If the opt-in carries at least one entry, its status enum must be
+# from the known set (paranoid: the status decoder didn't go off the
+# rails for some PS_* code).
+if [ "$OPT_IN_COUNT" -gt 0 ]; then
+	BOGUS=$(printf '%s' "$CURL_BODY" | jq \
+		'[.downloads[].status | select(. != "downloading" and . != "paused" and . != "completed" and . != "completing" and . != "hashing" and . != "erroneous" and . != "allocating" and . != "waiting" and . != "insufficient_disk" and . != "unknown")] | length')
+	if [ "$BOGUS" = "0" ]; then
+		_pass "/downloads?include_completed=1 all status values from known enum"
+	else
+		_fail "/downloads status enum allowlist" \
+			"$BOGUS entries have out-of-enum status"
+	fi
+fi
+
+# --- 3. Other truthy values: include_completed=true, =yes. --------
+for v in true yes; do
+	_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/downloads?include_completed=$v"
+	_assert_status 200 "GET /downloads?include_completed=$v → 200"
+	c=$(printf '%s' "$CURL_BODY" | jq '.downloads | length')
+	if [ "$c" = "$OPT_IN_COUNT" ]; then
+		_pass "include_completed=$v matches include_completed=1 ($c entries)"
+	else
+		_fail "include_completed=$v cardinality" \
+			"got $c entries, expected $OPT_IN_COUNT"
+	fi
+done
+
+# --- 4. include_completed=0 / =false / =garbage → default behavior. -
+for v in 0 false bogus; do
+	_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/downloads?include_completed=$v"
+	_assert_status 200 "GET /downloads?include_completed=$v → 200"
+	c=$(printf '%s' "$CURL_BODY" | jq '.downloads | length')
+	if [ "$c" = "$DEFAULT_COUNT" ]; then
+		_pass "include_completed=$v falls through to default ($c entries)"
+	else
+		_fail "include_completed=$v fallthrough" \
+			"got $c entries, expected $DEFAULT_COUNT (default)"
+	fi
+done
+
+# --- 5. Detail endpoint UNCHANGED — serves completed files too. ---
+#
+# Pick a hash from the opt-in response. If at least one entry is
+# completed, hitting its detail must still return 200 (consumers
+# asking for a specific file shouldn't be filtered).
+_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/downloads?include_completed=1"
+COMPLETED_HASH=$(printf '%s' "$CURL_BODY" | jq -r \
+	'[.downloads[] | select(.status == "completed")] | first | .hash // empty')
+if [ -n "$COMPLETED_HASH" ]; then
+	_curl -H "Authorization: Bearer $TOKEN" "$HOST/api/v0/downloads/$COMPLETED_HASH"
+	_assert_status 200 "GET /downloads/{completed-hash} → 200 (detail not filtered)"
+	_assert_json_eq '.status' completed \
+		'/downloads/{completed-hash} carries status=completed (decoder fix observable)'
+	_assert_json_eq '.hash' "$COMPLETED_HASH" \
+		'/downloads/{completed-hash} echoes the requested hash'
+else
+	echo "    info: no completed downloads in this daemon's queue; detail-not-filtered check skipped"
+fi
+
+# --- Summary. -----------------------------------------------------
+echo
+if [ "$FAIL_COUNT" -eq 0 ]; then
+	echo "OK: $TEST_COUNT/$TEST_COUNT passed"
+	exit 0
+fi
+echo "FAIL: $FAIL_COUNT/$TEST_COUNT failed"
+exit 1
diff --git a/unittests/curl-tests/amuleapi/12-downloads-add-patch.sh b/unittests/curl-tests/amuleapi/12-downloads-add-patch.sh
new file mode 100755
index 0000000000..bc16335c3a
--- /dev/null
+++ b/unittests/curl-tests/amuleapi/12-downloads-add-patch.sh
@@ -0,0 +1,299 @@
+#!/usr/bin/env bash
+#
+# amuleapi 12-downloads-add-patch — download lifecycle mutations.
+#
+# Endpoints landed:
+#   POST  /api/v0/downloads             — add a download by ed2k_link
+#   PATCH /api/v0/downloads/{hash}      — status/priority/category
+#
+# Mutate-then-refresh contract: every mutation handler runs
+# RefresherTick inline after the EC roundtrip succeeds, so the
+# response body AND the IMMEDIATE-next GET both reflect post-mutation
+# state. No sleep loops, no stale cache window. This smoke pins that
+# invariant — every PATCH is followed by a no-sleep GET that must
+# show the same state the PATCH response showed.
+#
+# The smoke uses the Ubuntu 24.04.4 ISO ed2k link as its test artifact
+# (provided by the operator). Hash:
+# 0031C9CBA65C50DD2015C184B2CA2C88. The ISO is a stable, well-seeded
+# ed2k file; amuled adds it to m_filelist within ~1 refresher tick.
+# 5b's smoke cleans up via DELETE.
+#
+# Role gate: mutations require ADMIN. Guest tokens get 403 forbidden.
+
+set -u
+set -o pipefail
+
+HOST=${HOST:-localhost:4713}
+ADMIN_PASS=${ADMIN_PASS:-adminpass}
+GUEST_PASS=${GUEST_PASS:-guestpass}
+
+# Stable test artifact: Ubuntu 24.04.4 desktop ISO. Lowercase hash as
+# stored on the API side (the wire path is case-insensitive but the
+# State cache is keyed in lowercase).
+TEST_LINK="ed2k://|file|ubuntu-24.04.4-desktop-amd64.iso|6655619072|0031C9CBA65C50DD2015C184B2CA2C88|/"
+TEST_HASH="0031c9cba65c50dd2015c184b2ca2c88"
+
+FAIL_COUNT=0
+TEST_COUNT=0
+
+CURL_BODY_FILE=$(mktemp -t amuleapi_12_downloads_add_patch_body.XXXXXX)
+trap '
+	rm -f "$CURL_BODY_FILE"
+	# Best-effort partfile cleanup so the Ubuntu ISO doesn'\''t survive
+	# a failed run and pin disk on the Windows VM (per
+	# feedback_clean_temp_partfiles_after_test).
+	if [ -n "${ADMIN_TOKEN:-}" ]; then
+		curl -s -X DELETE -H "Authorization: Bearer $ADMIN_TOKEN" \
+			"$HOST/api/v0/downloads/$TEST_HASH" > /dev/null 2>&1 || true
+	fi
+' EXIT
+
+_die()  { echo "FATAL: $*" >&2; exit 2; }
+_pass() { TEST_COUNT=$((TEST_COUNT+1)); echo "  PASS  $1"; }
+_fail() {
+	TEST_COUNT=$((TEST_COUNT+1)); FAIL_COUNT=$((FAIL_COUNT+1))
+	echo "  FAIL  $1"
+	shift
+	for arg in "$@"; do echo "        $arg"; done
+}
+
+_curl() {
+	local resp
+	resp=$(curl -s --max-time 10 -o "$CURL_BODY_FILE" -w '%{http_code}' "$@") \
+		|| _die "curl invocation failed for $*"
+	CURL_STATUS=$resp
+	CURL_BODY=$(cat "$CURL_BODY_FILE")
+}
+
+_assert_status() {
+	local expected=$1 label=$2
+	if [ "$CURL_STATUS" = "$expected" ]; then
+		_pass "$label (HTTP $CURL_STATUS)"
+	else
+		_fail "$label" "expected HTTP $expected, got $CURL_STATUS" \
+			"body head: $(printf '%s' "$CURL_BODY" | head -c 200)"
+	fi
+}
+
+_assert_json_eq() {
+	local expr=$1 expected=$2 label=$3
+	local actual
+	actual=$(printf '%s' "$CURL_BODY" | jq -r "$expr" 2>/dev/null) \
+		|| _fail "$label" "body was not valid JSON" "body: $CURL_BODY"
+	if [ "$actual" = "$expected" ]; then
+		_pass "$label"
+	else
+		_fail "$label" "expected $expected, got $actual" "body: $CURL_BODY"
+	fi
+}
+
+if ! command -v jq >/dev/null 2>&1; then
+	_die "jq is required."
+fi
+if ! curl -s -o /dev/null --max-time 2 "$HOST/api/v0/version" 2>/dev/null; then
+	_die "amuleapi at $HOST is not reachable."
+fi
+
+echo "amuleapi 12-downloads-add-patch smoke @ $HOST"
+
+ADMIN_TOKEN=$(curl -s -X POST -H "Content-Type: application/json" \
+	-d "{\"password\":\"$ADMIN_PASS\"}" \
+	"$HOST/api/v0/auth/login?type=bearer" | jq -r .token)
+[ -n "$ADMIN_TOKEN" ] && [ "$ADMIN_TOKEN" != "null" ] \
+	|| _die "admin login failed (need --set-admin-pass=$ADMIN_PASS on the daemon)"
+
+GUEST_TOKEN=$(curl -s -X POST -H "Content-Type: application/json" \
+	-d "{\"password\":\"$GUEST_PASS\"}" \
+	"$HOST/api/v0/auth/login?type=bearer" | jq -r .token)
+HAVE_GUEST=0
+if [ -n "$GUEST_TOKEN" ] && [ "$GUEST_TOKEN" != "null" ]; then
+	HAVE_GUEST=1
+fi
+
+sleep 4
+
+# --- 1. Auth gate (no token → 401). --------------------------------
+_curl -X POST -H "Content-Type: application/json" \
+	-d "{\"ed2k_link\":\"$TEST_LINK\"}" "$HOST/api/v0/downloads"
+_assert_status 401 "POST /downloads (no token) → 401"
+
+_curl -X PATCH -H "Content-Type: application/json" \
+	-d '{"status":"paused"}' "$HOST/api/v0/downloads/$TEST_HASH"
+_assert_status 401 "PATCH /downloads/{hash} (no token) → 401"
+
+# --- 2. Admin gate (guest → 403). ----------------------------------
+if [ "$HAVE_GUEST" = "1" ]; then
+	_curl -X POST -H "Authorization: Bearer $GUEST_TOKEN" \
+		-H "Content-Type: application/json" \
+		-d "{\"ed2k_link\":\"$TEST_LINK\"}" "$HOST/api/v0/downloads"
+	_assert_status 403 "POST /downloads (guest token) → 403"
+	_assert_json_eq '.error.code' forbidden \
+		'POST /downloads guest carries error.code=forbidden'
+
+	_curl -X PATCH -H "Authorization: Bearer $GUEST_TOKEN" \
+		-H "Content-Type: application/json" \
+		-d '{"status":"paused"}' "$HOST/api/v0/downloads/$TEST_HASH"
+	_assert_status 403 "PATCH /downloads/{hash} (guest token) → 403"
+else
+	echo "    info: no guest password set on daemon; admin-gate test skipped"
+fi
+
+# --- 3. POST /downloads happy: add the test ISO. -------------------
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d "{\"ed2k_link\":\"$TEST_LINK\"}" "$HOST/api/v0/downloads"
+_assert_status 202 "POST /downloads (Ubuntu ISO) → 202"
+_assert_json_eq '.ok' true 'POST /downloads response.ok==true'
+
+# Poll until the new partfile surfaces in /downloads (amuled's ADD_LINK
+# is async — allocation + hashing happen post-roundtrip). Bound at
+# ~5 s with 200 ms steps. Production refresher catches it in ≤1 tick.
+APPEARED=0
+for _ in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25; do
+	_curl -H "Authorization: Bearer $ADMIN_TOKEN" \
+		"$HOST/api/v0/downloads?include_completed=1"
+	if printf '%s' "$CURL_BODY" \
+	   | jq -e --arg h "$TEST_HASH" '.downloads[] | select(.hash == $h)' \
+	   >/dev/null 2>&1; then
+		APPEARED=1
+		break
+	fi
+	sleep 0.2
+done
+if [ "$APPEARED" = "1" ]; then
+	_pass "Ubuntu ISO surfaced in /downloads via async ADD_LINK"
+else
+	_die "Ubuntu ISO never surfaced; ADD_LINK semantics may have shifted"
+fi
+
+# --- 4. POST /downloads error paths. -------------------------------
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{"ed2k_link":"http://not-an-ed2k.com/foo"}' "$HOST/api/v0/downloads"
+_assert_status 400 "POST /downloads (non-ed2k URL) → 400"
+_assert_json_eq '.error.code' bad_request \
+	'POST /downloads invalid URL carries error.code=bad_request'
+
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{}' "$HOST/api/v0/downloads"
+_assert_status 400 "POST /downloads (missing ed2k_link) → 400"
+
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d 'not json' "$HOST/api/v0/downloads"
+_assert_status 400 "POST /downloads (malformed JSON) → 400"
+
+# --- 5. PATCH happy paths + no-stale-cache invariant. --------------
+#
+# Save the pre-mutation state so we can restore it at the end.
+_curl -H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/downloads/$TEST_HASH"
+SAVED_STATUS=$(printf '%s' "$CURL_BODY" | jq -r '.status')
+SAVED_PRIORITY=$(printf '%s' "$CURL_BODY" | jq -r '.priority')
+SAVED_CATEGORY=$(printf '%s' "$CURL_BODY" | jq -r '.category')
+echo "    info: saved state status=$SAVED_STATUS priority=$SAVED_PRIORITY category=$SAVED_CATEGORY"
+
+# 5a. PATCH status=paused. Response body must show paused. Immediate
+# GET (no sleep) must also show paused — pins the mutate-then-refresh
+# contract.
+_curl -X PATCH -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{"status":"paused"}' "$HOST/api/v0/downloads/$TEST_HASH"
+_assert_status 200 "PATCH /downloads/{hash} status=paused → 200"
+_assert_json_eq '.status' paused \
+	'PATCH response body shows status=paused'
+
+# No sleep — IMMEDIATE GET. Must see the post-mutation value.
+_curl -H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/downloads/$TEST_HASH"
+_assert_json_eq '.status' paused \
+	'IMMEDIATE GET after PATCH paused shows status=paused (no stale cache)'
+
+# 5b. PATCH status=resumed. Same invariant in the opposite direction.
+_curl -X PATCH -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{"status":"resumed"}' "$HOST/api/v0/downloads/$TEST_HASH"
+_assert_status 200 "PATCH /downloads/{hash} status=resumed → 200"
+_curl -H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/downloads/$TEST_HASH"
+# Resumed maps back to one of the live statuses (downloading / waiting).
+RESUMED=$(printf '%s' "$CURL_BODY" | jq -r '.status')
+if [ "$RESUMED" = "paused" ]; then
+	_fail "IMMEDIATE GET after PATCH resumed" \
+		"still shows status=paused (stale cache)"
+else
+	_pass "IMMEDIATE GET after PATCH resumed shows non-paused (status=$RESUMED)"
+fi
+
+# 5c. PATCH priority=release. Response + immediate GET both show
+# release.
+_curl -X PATCH -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{"priority":"release"}' "$HOST/api/v0/downloads/$TEST_HASH"
+_assert_status 200 "PATCH priority=release → 200"
+_assert_json_eq '.priority' release 'PATCH response shows priority=release'
+_curl -H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/downloads/$TEST_HASH"
+_assert_json_eq '.priority' release \
+	'IMMEDIATE GET after PATCH priority=release shows priority=release'
+
+# 5d. Combined PATCH — status + priority + category in one body.
+_curl -X PATCH -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{"status":"paused","priority":"low","category":0}' \
+	"$HOST/api/v0/downloads/$TEST_HASH"
+_assert_status 200 "PATCH combined (status+priority+category) → 200"
+_assert_json_eq '.status'   paused 'combined PATCH response status=paused'
+_assert_json_eq '.priority' low    'combined PATCH response priority=low'
+_assert_json_eq '.category' 0      'combined PATCH response category=0'
+_curl -H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/downloads/$TEST_HASH"
+_assert_json_eq '.status'   paused 'IMMEDIATE GET after combined PATCH status=paused'
+_assert_json_eq '.priority' low    'IMMEDIATE GET after combined PATCH priority=low'
+
+# --- 6. PATCH error paths. -----------------------------------------
+_curl -X PATCH -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{}' "$HOST/api/v0/downloads/$TEST_HASH"
+_assert_status 400 "PATCH empty body → 400"
+
+_curl -X PATCH -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{"priority":"bogus"}' "$HOST/api/v0/downloads/$TEST_HASH"
+_assert_status 400 "PATCH unknown priority enum → 400"
+
+_curl -X PATCH -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{"status":"flapped"}' "$HOST/api/v0/downloads/$TEST_HASH"
+_assert_status 400 "PATCH unknown status enum → 400"
+
+_curl -X PATCH -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{"status":"paused"}' "$HOST/api/v0/downloads/baadbaadbaadbaadbaadbaadbaadbaad"
+_assert_status 404 "PATCH unknown hash → 404"
+
+# --- 7. Restore the pre-mutation state so the Ubuntu ISO ends up
+# in roughly the state it started in. (5b's smoke will clean it up
+# via DELETE.)
+RESTORE_STATUS=$SAVED_STATUS
+case "$RESTORE_STATUS" in
+	downloading|waiting|hashing|completing|allocating) RESTORE_STATUS=resumed ;;
+	paused|completed|erroneous|insufficient_disk) RESTORE_STATUS=paused ;;
+	*) RESTORE_STATUS=resumed ;;
+esac
+_curl -X PATCH -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d "{\"status\":\"$RESTORE_STATUS\",\"priority\":\"$SAVED_PRIORITY\",\"category\":$SAVED_CATEGORY}" \
+	"$HOST/api/v0/downloads/$TEST_HASH"
+_assert_status 200 "PATCH (restore pre-mutation state) → 200"
+
+# --- Summary. -----------------------------------------------------
+echo
+if [ "$FAIL_COUNT" -eq 0 ]; then
+	echo "OK: $TEST_COUNT/$TEST_COUNT passed"
+	exit 0
+fi
+echo "FAIL: $FAIL_COUNT/$TEST_COUNT failed"
+exit 1
diff --git a/unittests/curl-tests/amuleapi/13-downloads-delete-clear.sh b/unittests/curl-tests/amuleapi/13-downloads-delete-clear.sh
new file mode 100755
index 0000000000..6a512083da
--- /dev/null
+++ b/unittests/curl-tests/amuleapi/13-downloads-delete-clear.sh
@@ -0,0 +1,294 @@
+#!/usr/bin/env bash
+#
+# amuleapi 13-downloads-delete-clear — clear / delete downloads.
+#
+# Endpoints:
+#   DELETE /api/v0/downloads/{hash}             — drop a single entry
+#   POST   /api/v0/downloads/clear_completed    — drop all completed
+#
+# Routing by current state:
+#   * status == "completed" → EC_OP_CLEAR_COMPLETED (by ECID; targets
+#                            amuled's m_completedDownloads list)
+#   * any other status      → EC_OP_PARTFILE_DELETE (by hash; targets
+#                            active partfiles in m_filelist)
+#
+# The Phase 4h status-decode fix is load-bearing here: a finished
+# partfile that the prior decoder reported as "paused" would never
+# be enumerable by clear_completed. Phase 5b's bulk endpoint walks
+# the cache for `status=="completed"` entries, so the decoder must
+# surface the wire string correctly.
+#
+# Same no-stale-cache invariant as 5a: DELETE response followed by
+# an IMMEDIATE GET must show the entry gone (404).
+
+set -u
+set -o pipefail
+
+HOST=${HOST:-localhost:4713}
+ADMIN_PASS=${ADMIN_PASS:-adminpass}
+GUEST_PASS=${GUEST_PASS:-guestpass}
+
+TEST_LINK="ed2k://|file|ubuntu-24.04.4-desktop-amd64.iso|6655619072|0031C9CBA65C50DD2015C184B2CA2C88|/"
+TEST_HASH="0031c9cba65c50dd2015c184b2ca2c88"
+
+FAIL_COUNT=0
+TEST_COUNT=0
+
+CURL_BODY_FILE=$(mktemp -t amuleapi_13_downloads_delete_clear_body.XXXXXX)
+trap 'rm -f "$CURL_BODY_FILE"' EXIT
+
+_die()  { echo "FATAL: $*" >&2; exit 2; }
+_pass() { TEST_COUNT=$((TEST_COUNT+1)); echo "  PASS  $1"; }
+_skip() { TEST_COUNT=$((TEST_COUNT+1)); echo "  SKIP  $1"; }
+_fail() {
+	TEST_COUNT=$((TEST_COUNT+1)); FAIL_COUNT=$((FAIL_COUNT+1))
+	echo "  FAIL  $1"
+	shift
+	for arg in "$@"; do echo "        $arg"; done
+}
+
+_curl() {
+	local resp
+	resp=$(curl -s --max-time 10 -o "$CURL_BODY_FILE" -w '%{http_code}' "$@") \
+		|| _die "curl invocation failed for $*"
+	CURL_STATUS=$resp
+	CURL_BODY=$(cat "$CURL_BODY_FILE")
+}
+
+_assert_status() {
+	local expected=$1 label=$2
+	if [ "$CURL_STATUS" = "$expected" ]; then
+		_pass "$label (HTTP $CURL_STATUS)"
+	else
+		_fail "$label" "expected HTTP $expected, got $CURL_STATUS" \
+			"body head: $(printf '%s' "$CURL_BODY" | head -c 200)"
+	fi
+}
+
+_assert_json_eq() {
+	local expr=$1 expected=$2 label=$3
+	local actual
+	actual=$(printf '%s' "$CURL_BODY" | jq -r "$expr" 2>/dev/null) \
+		|| _fail "$label" "body was not valid JSON" "body: $CURL_BODY"
+	if [ "$actual" = "$expected" ]; then
+		_pass "$label"
+	else
+		_fail "$label" "expected $expected, got $actual" "body: $CURL_BODY"
+	fi
+}
+
+if ! command -v jq >/dev/null 2>&1; then _die "jq is required."; fi
+if ! curl -s -o /dev/null --max-time 2 "$HOST/api/v0/version" 2>/dev/null; then
+	_die "amuleapi at $HOST is not reachable."
+fi
+
+echo "amuleapi 13-downloads-delete-clear smoke @ $HOST"
+
+ADMIN_TOKEN=$(curl -s -X POST -H "Content-Type: application/json" \
+	-d "{\"password\":\"$ADMIN_PASS\"}" "$HOST/api/v0/auth/login?type=bearer" | jq -r .token)
+[ -n "$ADMIN_TOKEN" ] && [ "$ADMIN_TOKEN" != "null" ] || _die "admin login failed"
+
+GUEST_TOKEN=$(curl -s -X POST -H "Content-Type: application/json" \
+	-d "{\"password\":\"$GUEST_PASS\"}" "$HOST/api/v0/auth/login?type=bearer" | jq -r .token)
+HAVE_GUEST=0
+[ -n "$GUEST_TOKEN" ] && [ "$GUEST_TOKEN" != "null" ] && HAVE_GUEST=1
+
+sleep 4
+
+# --- 1. Auth + admin gate. -----------------------------------------
+_curl -X DELETE "$HOST/api/v0/downloads/$TEST_HASH"
+_assert_status 401 "DELETE /downloads/{hash} (no token) → 401"
+
+_curl -X POST "$HOST/api/v0/downloads/clear_completed"
+_assert_status 401 "POST /downloads/clear_completed (no token) → 401"
+
+if [ "$HAVE_GUEST" = "1" ]; then
+	_curl -X DELETE -H "Authorization: Bearer $GUEST_TOKEN" \
+		"$HOST/api/v0/downloads/$TEST_HASH"
+	_assert_status 403 "DELETE /downloads/{hash} (guest) → 403"
+	_curl -X POST -H "Authorization: Bearer $GUEST_TOKEN" \
+		"$HOST/api/v0/downloads/clear_completed"
+	_assert_status 403 "POST /downloads/clear_completed (guest) → 403"
+else
+	echo "    info: no guest pass; admin-gate skipped"
+fi
+
+# --- 2. DELETE non-existent hash → 404. ----------------------------
+_curl -X DELETE -H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/downloads/baadbaadbaadbaadbaadbaadbaadbaad"
+_assert_status 404 "DELETE /downloads/{nonexistent} → 404"
+
+# --- 3. Bulk clear_completed on a clean queue (no completed). ------
+#
+# Pre-seed: clear anything that's already completed so we measure
+# from a known baseline. (The smoke is order-independent — 11-downloads-default-filter
+# may have left a completed entry behind, or it may not have. We
+# call clear once to baseline, then move on.)
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/downloads/clear_completed"
+_assert_status 200 "POST /downloads/clear_completed (baseline) → 200"
+_assert_json_eq '.ok' true 'clear_completed baseline response.ok==true'
+
+# Second call: now nothing is completed. cleared must be 0.
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/downloads/clear_completed"
+_assert_status 200 "POST /downloads/clear_completed (idempotent no-op) → 200"
+_assert_json_eq '.cleared' 0 'clear_completed second call cleared 0 entries'
+
+# --- 4. DELETE on an active partfile (happy path + no-stale GET). --
+#
+# Add the Ubuntu ISO, wait for it to surface, DELETE it, immediate
+# GET must 404. This pins the mutate-then-refresh invariant on the
+# active-path EC_OP_PARTFILE_DELETE branch.
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d "{\"ed2k_link\":\"$TEST_LINK\"}" "$HOST/api/v0/downloads"
+_assert_status 202 "POST /downloads (Ubuntu ISO) → 202 (setup)"
+
+APPEARED=0
+for _ in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25; do
+	_curl -H "Authorization: Bearer $ADMIN_TOKEN" \
+		"$HOST/api/v0/downloads?include_completed=1"
+	if printf '%s' "$CURL_BODY" \
+	   | jq -e --arg h "$TEST_HASH" '.downloads[] | select(.hash == $h)' \
+	   >/dev/null 2>&1; then
+		APPEARED=1
+		break
+	fi
+	sleep 0.2
+done
+[ "$APPEARED" = "1" ] || _die "Ubuntu ISO never surfaced after POST"
+_pass "Ubuntu ISO surfaced for DELETE setup"
+
+# DELETE it.
+_curl -X DELETE -H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/downloads/$TEST_HASH"
+_assert_status 200 "DELETE /downloads/{Ubuntu ISO hash} → 200"
+_assert_json_eq '.ok'   true        'DELETE response.ok==true'
+_assert_json_eq '.hash' "$TEST_HASH" 'DELETE response echoes hash'
+
+# Immediate GET — no stale cache.
+_curl -H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/downloads/$TEST_HASH"
+_assert_status 404 "IMMEDIATE GET after DELETE → 404 (no stale cache)"
+
+# Same in list view — entry must be gone from the default response.
+_curl -H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/downloads?include_completed=1"
+STILL_THERE=$(printf '%s' "$CURL_BODY" \
+	| jq --arg h "$TEST_HASH" '[.downloads[] | select(.hash == $h)] | length')
+if [ "$STILL_THERE" = "0" ]; then
+	_pass "/downloads (list) no longer contains the deleted hash"
+else
+	_fail "/downloads list staleness" \
+		"deleted entry still appears in list response"
+fi
+
+# --- 5. DELETE on the same hash twice → 404 second time. ----------
+_curl -X DELETE -H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/downloads/$TEST_HASH"
+_assert_status 404 "DELETE the same hash twice → 404 second time"
+
+# --- 6. POST clear_completed {hash:...} on non-existent → 404. ----
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{"hash":"baadbaadbaadbaadbaadbaadbaadbaad"}' \
+	"$HOST/api/v0/downloads/clear_completed"
+_assert_status 404 "POST clear_completed {hash:unknown} → 404"
+_assert_json_eq '.error.code' not_found 'clear_completed {hash:unknown}.error.code'
+
+# --- 7. POST clear_completed malformed body → 400. ----------------
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d 'not json at all' \
+	"$HOST/api/v0/downloads/clear_completed"
+_assert_status 400 "POST clear_completed (malformed body) → 400"
+
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{"hash": 12345}' \
+	"$HOST/api/v0/downloads/clear_completed"
+_assert_status 400 "POST clear_completed {hash: non-string} → 400"
+
+# --- 8. POST clear_completed {hash:active-partfile} → 409. --------
+#
+# Re-add the Ubuntu ISO so we have a known active partfile, then
+# call clear_completed with that hash. The handler must refuse with
+# 409 not_completed because the entry is in m_filelist, not in
+# m_completedDownloads.
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d "{\"ed2k_link\":\"$TEST_LINK\"}" "$HOST/api/v0/downloads"
+_assert_status 202 "POST /downloads (Ubuntu ISO re-add) → 202 (setup)"
+
+APPEARED=0
+for _ in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25; do
+	_curl -H "Authorization: Bearer $ADMIN_TOKEN" \
+		"$HOST/api/v0/downloads?include_completed=1"
+	if printf '%s' "$CURL_BODY" \
+	   | jq -e --arg h "$TEST_HASH" '.downloads[] | select(.hash == $h)' \
+	   >/dev/null 2>&1; then
+		APPEARED=1
+		break
+	fi
+	sleep 0.2
+done
+[ "$APPEARED" = "1" ] || _die "Ubuntu ISO never re-surfaced after re-POST"
+
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d "{\"hash\":\"$TEST_HASH\"}" \
+	"$HOST/api/v0/downloads/clear_completed"
+_assert_status 409 "POST clear_completed {hash:active-partfile} → 409"
+_assert_json_eq '.error.code' not_completed \
+	'clear_completed active hash .error.code == not_completed'
+
+# Cleanup the active partfile.
+_curl -X DELETE -H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/downloads/$TEST_HASH"
+_assert_status 200 "Cleanup: DELETE /downloads/{Ubuntu ISO hash} (2nd) → 200"
+
+# --- 9. DELETE / clear_completed against any naturally-completed
+#         entry — covers the by-hash success path AND the 409 from
+#         DELETE on a completed entry. SKIP if the daemon has none.
+_curl -H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/downloads?include_completed=1"
+COMPLETED_HASH=$(printf '%s' "$CURL_BODY" \
+	| jq -r '[.downloads[] | select(.status == "completed") | .hash][0] // empty')
+if [ -n "$COMPLETED_HASH" ]; then
+	# DELETE must refuse with 409 + actionable error code.
+	_curl -X DELETE -H "Authorization: Bearer $ADMIN_TOKEN" \
+		"$HOST/api/v0/downloads/$COMPLETED_HASH"
+	_assert_status 409 "DELETE /downloads/{completed} → 409"
+	_assert_json_eq '.error.code' completed_use_clear_completed \
+		'DELETE on completed .error.code == completed_use_clear_completed'
+
+	# clear_completed {hash:completed} → 200, exactly 1 cleared.
+	_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+		-H "Content-Type: application/json" \
+		-d "{\"hash\":\"$COMPLETED_HASH\"}" \
+		"$HOST/api/v0/downloads/clear_completed"
+	_assert_status 200 "POST clear_completed {hash:completed} → 200"
+	_assert_json_eq '.cleared' 1 'per-hash clear_completed cleared exactly 1'
+	_assert_json_eq ".cleared_hashes[0]" "$COMPLETED_HASH" \
+		'cleared_hashes echoes the input hash'
+
+	# Second call → 404 (entry is gone).
+	_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+		-H "Content-Type: application/json" \
+		-d "{\"hash\":\"$COMPLETED_HASH\"}" \
+		"$HOST/api/v0/downloads/clear_completed"
+	_assert_status 404 "POST clear_completed {hash:already-cleared} → 404"
+else
+	_skip "DELETE on completed → 409 (no completed entry in test daemon)"
+	_skip "POST clear_completed {hash:completed} → 200 (no completed entry)"
+fi
+
+# --- Summary. -----------------------------------------------------
+echo
+if [ "$FAIL_COUNT" -eq 0 ]; then
+	echo "OK: $TEST_COUNT/$TEST_COUNT passed"
+	exit 0
+fi
+echo "FAIL: $FAIL_COUNT/$TEST_COUNT failed"
+exit 1
diff --git a/unittests/curl-tests/amuleapi/14-servers-mutations.sh b/unittests/curl-tests/amuleapi/14-servers-mutations.sh
new file mode 100755
index 0000000000..46b398244a
--- /dev/null
+++ b/unittests/curl-tests/amuleapi/14-servers-mutations.sh
@@ -0,0 +1,268 @@
+#!/usr/bin/env bash
+#
+# amuleapi 14-servers-mutations — server lifecycle mutations.
+#
+# Endpoints:
+#   POST   /api/v0/servers                   — add by {address, name?}
+#   POST   /api/v0/servers/{ecid}/connect    — connect to one server
+#   DELETE /api/v0/servers/{ecid}            — remove from the list
+#
+# All keyed by ECID on the URL — the EC ops (CONNECT/REMOVE) actually
+# identify the server by IPv4+port server-side, so the handler looks
+# up the cache entry by ECID and builds the EC_TAG_SERVER tag from the
+# cached IP+port. Phase 5c also fixed a latent /servers[].address
+# bug: the GET_UPDATE (Phase 4f) per-server tag carries IP/port in
+# CHILD tags (EC_TAG_SERVER_IP + EC_TAG_SERVER_PORT) rather than the
+# outer-tag IPv4 shape the legacy GET_SERVER_LIST used. /servers[]
+# was showing "0.0.0.0:0" for every entry; smoke pins the fix.
+#
+# Test server: a real eMule server (185.65.45.144:4232 = eDonkey
+# Sicherheit) the operator added to amuled's serverlist before
+# starting the smoke. We POST a duplicate to test the
+# amuled-rejected error path, then DELETE the original.
+
+set -u
+set -o pipefail
+
+HOST=${HOST:-localhost:4713}
+ADMIN_PASS=${ADMIN_PASS:-adminpass}
+GUEST_PASS=${GUEST_PASS:-guestpass}
+
+# Test server (host:port). The operator's daemon has a few dozen
+# servers configured; the smoke adds a name we can target by string
+# search and cleans it up at the end.
+TEST_ADDRESS="185.65.45.144:4232"
+TEST_NAME="14-servers-mutations-smoke-tag"
+
+FAIL_COUNT=0
+TEST_COUNT=0
+
+CURL_BODY_FILE=$(mktemp -t amuleapi_14_servers_mutations_body.XXXXXX)
+trap 'rm -f "$CURL_BODY_FILE"' EXIT
+
+_die()  { echo "FATAL: $*" >&2; exit 2; }
+_pass() { TEST_COUNT=$((TEST_COUNT+1)); echo "  PASS  $1"; }
+_fail() {
+	TEST_COUNT=$((TEST_COUNT+1)); FAIL_COUNT=$((FAIL_COUNT+1))
+	echo "  FAIL  $1"
+	shift
+	for arg in "$@"; do echo "        $arg"; done
+}
+
+_curl() {
+	local resp
+	resp=$(curl -s --max-time 10 -o "$CURL_BODY_FILE" -w '%{http_code}' "$@") \
+		|| _die "curl invocation failed for $*"
+	CURL_STATUS=$resp
+	CURL_BODY=$(cat "$CURL_BODY_FILE")
+}
+
+_assert_status() {
+	local expected=$1 label=$2
+	if [ "$CURL_STATUS" = "$expected" ]; then
+		_pass "$label (HTTP $CURL_STATUS)"
+	else
+		_fail "$label" "expected HTTP $expected, got $CURL_STATUS" \
+			"body head: $(printf '%s' "$CURL_BODY" | head -c 200)"
+	fi
+}
+
+_assert_json_eq() {
+	local expr=$1 expected=$2 label=$3
+	local actual
+	actual=$(printf '%s' "$CURL_BODY" | jq -r "$expr" 2>/dev/null) \
+		|| _fail "$label" "body was not valid JSON" "body: $CURL_BODY"
+	if [ "$actual" = "$expected" ]; then
+		_pass "$label"
+	else
+		_fail "$label" "expected $expected, got $actual" "body: $CURL_BODY"
+	fi
+}
+
+if ! command -v jq >/dev/null 2>&1; then _die "jq is required."; fi
+if ! curl -s -o /dev/null --max-time 2 "$HOST/api/v0/version" 2>/dev/null; then
+	_die "amuleapi at $HOST is not reachable."
+fi
+
+echo "amuleapi 14-servers-mutations smoke @ $HOST"
+
+ADMIN_TOKEN=$(curl -s -X POST -H "Content-Type: application/json" \
+	-d "{\"password\":\"$ADMIN_PASS\"}" "$HOST/api/v0/auth/login?type=bearer" | jq -r .token)
+[ -n "$ADMIN_TOKEN" ] && [ "$ADMIN_TOKEN" != "null" ] || _die "admin login failed"
+
+GUEST_TOKEN=$(curl -s -X POST -H "Content-Type: application/json" \
+	-d "{\"password\":\"$GUEST_PASS\"}" "$HOST/api/v0/auth/login?type=bearer" | jq -r .token)
+HAVE_GUEST=0
+[ -n "$GUEST_TOKEN" ] && [ "$GUEST_TOKEN" != "null" ] && HAVE_GUEST=1
+
+sleep 4
+
+# --- 1. /servers[] address parse fix — must not be "0.0.0.0:0". ---
+_curl -H "Authorization: Bearer $ADMIN_TOKEN" "$HOST/api/v0/servers"
+_assert_status 200 "GET /servers → 200"
+
+# The operator's daemon has servers in its list with real IPs.
+# Smoke would pass on an empty list (no servers means no parse path
+# to exercise), but if there ARE servers, NONE should report the
+# all-zeros sentinel — that was the GET_UPDATE child-tag parse bug.
+N=$(printf '%s' "$CURL_BODY" | jq '.servers | length')
+if [ "$N" -gt 0 ]; then
+	BOGUS=$(printf '%s' "$CURL_BODY" | jq \
+		'[.servers[] | select(.address == "0.0.0.0:0")] | length')
+	if [ "$BOGUS" = "0" ]; then
+		_pass "/servers[].address parses real IP:port (no \"0.0.0.0:0\" entries, $N servers checked)"
+	else
+		_fail "/servers[].address parse regression" \
+			"$BOGUS / $N entries report \"0.0.0.0:0\""
+	fi
+	# `ecid` field must be present (URL key for the mutation endpoints).
+	BAD_ECID=$(printf '%s' "$CURL_BODY" | jq '[.servers[] | select(.ecid == null)] | length')
+	if [ "$BAD_ECID" = "0" ]; then
+		_pass "/servers[].ecid populated for every entry"
+	else
+		_fail "/servers[].ecid missing" \
+			"$BAD_ECID entries lack the ecid field"
+	fi
+else
+	echo "    info: daemon has 0 servers configured; parse-bug check skipped"
+fi
+
+# --- 2. Auth + admin gate. -----------------------------------------
+_curl -X POST -H "Content-Type: application/json" \
+	-d "{\"address\":\"$TEST_ADDRESS\"}" "$HOST/api/v0/servers"
+_assert_status 401 "POST /servers (no token) → 401"
+
+_curl -X DELETE "$HOST/api/v0/servers/1"
+_assert_status 401 "DELETE /servers/{ecid} (no token) → 401"
+
+_curl -X POST "$HOST/api/v0/servers/1/connect"
+_assert_status 401 "POST /servers/{ecid}/connect (no token) → 401"
+
+if [ "$HAVE_GUEST" = "1" ]; then
+	_curl -X POST -H "Authorization: Bearer $GUEST_TOKEN" \
+		-H "Content-Type: application/json" \
+		-d "{\"address\":\"$TEST_ADDRESS\"}" "$HOST/api/v0/servers"
+	_assert_status 403 "POST /servers (guest) → 403"
+	_curl -X DELETE -H "Authorization: Bearer $GUEST_TOKEN" \
+		"$HOST/api/v0/servers/1"
+	_assert_status 403 "DELETE /servers/{ecid} (guest) → 403"
+	_curl -X POST -H "Authorization: Bearer $GUEST_TOKEN" \
+		"$HOST/api/v0/servers/1/connect"
+	_assert_status 403 "POST /servers/{ecid}/connect (guest) → 403"
+else
+	echo "    info: no guest pass; admin-gate skipped"
+fi
+
+# --- 3. POST /servers happy path — add the tagged server. ---------
+#
+# amuled treats duplicate (host:port) adds as rejections; if the
+# server already exists with the same address, we'll get 400
+# amuled_rejected. Strip any prior tag of the same name first so the
+# smoke is idempotent (no DELETE in the orchestrator yet for older
+# entries).
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d "{\"address\":\"$TEST_ADDRESS\",\"name\":\"$TEST_NAME\"}" \
+	"$HOST/api/v0/servers"
+# Accept 201 (fresh add) OR 400 (already in list — server was added
+# by a prior smoke or the operator). Both are valid endings.
+if [ "$CURL_STATUS" = "201" ]; then
+	_pass "POST /servers (add tagged server) → 201"
+elif [ "$CURL_STATUS" = "400" ]; then
+	ERR_CODE=$(printf '%s' "$CURL_BODY" | jq -r '.error.code')
+	if [ "$ERR_CODE" = "amuled_rejected" ]; then
+		_pass "POST /servers (already in list) → 400 amuled_rejected"
+	else
+		_fail "POST /servers" \
+			"got 400 with unexpected error.code=$ERR_CODE"
+	fi
+else
+	_fail "POST /servers" \
+		"expected 201 or 400, got $CURL_STATUS" \
+		"body: $CURL_BODY"
+fi
+
+# Wait for the new server to land in cache (no inline refresh needed
+# — POST handler runs RefresherTick before returning).
+_curl -H "Authorization: Bearer $ADMIN_TOKEN" "$HOST/api/v0/servers"
+ECID=$(printf '%s' "$CURL_BODY" \
+	| jq -r --arg n "$TEST_NAME" \
+	  '[.servers[] | select(.name == $n)] | first | .ecid // empty')
+if [ -n "$ECID" ] && [ "$ECID" != "null" ]; then
+	_pass "Tagged server present in /servers (ecid=$ECID)"
+else
+	_fail "Tagged server lookup" \
+		"could not find server with name=$TEST_NAME in /servers"
+	_die "cannot continue without the test server ECID"
+fi
+
+# --- 4. POST /servers error paths. ---------------------------------
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{}' "$HOST/api/v0/servers"
+_assert_status 400 "POST /servers (no address) → 400"
+
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{"address":"no-colon"}' "$HOST/api/v0/servers"
+_assert_status 400 "POST /servers (no colon in address) → 400"
+
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d 'not json' "$HOST/api/v0/servers"
+_assert_status 400 "POST /servers (malformed JSON) → 400"
+
+# --- 5. POST /servers/{ecid}/connect. ------------------------------
+#
+# This kicks off an ed2k connect attempt. amuled accepts the command
+# (returns NOOP); the actual TCP connect is async. 202 Accepted.
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/servers/$ECID/connect"
+_assert_status 202 "POST /servers/{ecid}/connect → 202"
+_assert_json_eq '.ok' true 'connect response.ok==true'
+
+# Bad ECID → 400 (path can't parse), or 404 (parses but no match).
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/servers/not-a-number/connect"
+_assert_status 400 "POST /servers/not-a-number/connect → 400"
+
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/servers/4294967295/connect"
+_assert_status 404 "POST /servers/{unknown ecid}/connect → 404"
+
+# --- 6. DELETE /servers/{ecid} happy path + no-stale invariant. ---
+_curl -X DELETE -H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/servers/$ECID"
+_assert_status 200 "DELETE /servers/$ECID → 200"
+_assert_json_eq '.ok'   true        'DELETE response.ok==true'
+_assert_json_eq '.ecid' "$ECID"     'DELETE response echoes ecid'
+
+# Immediate GET — entry must be gone from the cache.
+_curl -H "Authorization: Bearer $ADMIN_TOKEN" "$HOST/api/v0/servers"
+STILL_THERE=$(printf '%s' "$CURL_BODY" \
+	| jq --arg n "$TEST_NAME" \
+	  '[.servers[] | select(.name == $n)] | length')
+if [ "$STILL_THERE" = "0" ]; then
+	_pass "/servers no longer contains the deleted tagged server (no stale cache)"
+else
+	_fail "/servers staleness after DELETE" \
+		"$TEST_NAME still present after DELETE"
+fi
+
+# --- 7. DELETE error paths. ----------------------------------------
+_curl -X DELETE -H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/servers/$ECID"
+_assert_status 404 "DELETE /servers/{just-deleted ecid} → 404"
+
+_curl -X DELETE -H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/servers/not-a-number"
+_assert_status 400 "DELETE /servers/not-a-number → 400"
+
+# --- Summary. -----------------------------------------------------
+echo
+if [ "$FAIL_COUNT" -eq 0 ]; then
+	echo "OK: $TEST_COUNT/$TEST_COUNT passed"
+	exit 0
+fi
+echo "FAIL: $FAIL_COUNT/$TEST_COUNT failed"
+exit 1
diff --git a/unittests/curl-tests/amuleapi/15-preferences-patch.sh b/unittests/curl-tests/amuleapi/15-preferences-patch.sh
new file mode 100755
index 0000000000..121f0079d1
--- /dev/null
+++ b/unittests/curl-tests/amuleapi/15-preferences-patch.sh
@@ -0,0 +1,208 @@
+#!/usr/bin/env bash
+#
+# amuleapi 15-preferences-patch — PATCH /preferences.
+#
+# Endpoint:
+#   PATCH /api/v0/preferences
+#       body: { general?: {...}, connection?: {...} }
+#
+# Wire shape mirrors the /preferences GET response. Both sub-objects
+# optional; all fields within optional. Only fields present are
+# applied. Returns 200 with the post-mutation /preferences body so
+# consumers can confirm what landed without a follow-up GET.
+#
+# EC packet shape: `EC_OP_SET_PREFERENCES` at `EC_DETAIL_FULL`. FULL
+# is required so amuled's CEC_Prefs_Packet::Apply() honors boolean
+# tags (it gates ApplyBoolean on `use_tag = (detail == FULL)` per
+# ECSpecialMuleTags.cpp:392).
+#
+# No-stale-cache invariant: PATCH returns the post-mutation state in
+# its response body AND the immediate-following GET shows the same
+# values. RefresherTick is called inline after every successful
+# SET_PREFERENCES roundtrip.
+
+set -u
+set -o pipefail
+
+HOST=${HOST:-localhost:4713}
+ADMIN_PASS=${ADMIN_PASS:-adminpass}
+GUEST_PASS=${GUEST_PASS:-guestpass}
+
+FAIL_COUNT=0
+TEST_COUNT=0
+
+CURL_BODY_FILE=$(mktemp -t amuleapi_15_preferences_patch_body.XXXXXX)
+trap 'rm -f "$CURL_BODY_FILE"' EXIT
+
+_die()  { echo "FATAL: $*" >&2; exit 2; }
+_pass() { TEST_COUNT=$((TEST_COUNT+1)); echo "  PASS  $1"; }
+_fail() {
+	TEST_COUNT=$((TEST_COUNT+1)); FAIL_COUNT=$((FAIL_COUNT+1))
+	echo "  FAIL  $1"
+	shift
+	for arg in "$@"; do echo "        $arg"; done
+}
+
+_curl() {
+	local resp
+	resp=$(curl -s --max-time 10 -o "$CURL_BODY_FILE" -w '%{http_code}' "$@") \
+		|| _die "curl invocation failed for $*"
+	CURL_STATUS=$resp
+	CURL_BODY=$(cat "$CURL_BODY_FILE")
+}
+
+_assert_status() {
+	local expected=$1 label=$2
+	if [ "$CURL_STATUS" = "$expected" ]; then
+		_pass "$label (HTTP $CURL_STATUS)"
+	else
+		_fail "$label" "expected HTTP $expected, got $CURL_STATUS" \
+			"body head: $(printf '%s' "$CURL_BODY" | head -c 200)"
+	fi
+}
+
+_assert_json_eq() {
+	local expr=$1 expected=$2 label=$3
+	local actual
+	actual=$(printf '%s' "$CURL_BODY" | jq -r "$expr" 2>/dev/null) \
+		|| _fail "$label" "body was not valid JSON" "body: $CURL_BODY"
+	if [ "$actual" = "$expected" ]; then
+		_pass "$label"
+	else
+		_fail "$label" "expected $expected, got $actual" "body: $CURL_BODY"
+	fi
+}
+
+if ! command -v jq >/dev/null 2>&1; then _die "jq is required."; fi
+if ! curl -s -o /dev/null --max-time 2 "$HOST/api/v0/version" 2>/dev/null; then
+	_die "amuleapi at $HOST is not reachable."
+fi
+
+echo "amuleapi 15-preferences-patch smoke @ $HOST"
+
+ADMIN_TOKEN=$(curl -s -X POST -H "Content-Type: application/json" \
+	-d "{\"password\":\"$ADMIN_PASS\"}" "$HOST/api/v0/auth/login?type=bearer" | jq -r .token)
+[ -n "$ADMIN_TOKEN" ] && [ "$ADMIN_TOKEN" != "null" ] || _die "admin login failed"
+
+GUEST_TOKEN=$(curl -s -X POST -H "Content-Type: application/json" \
+	-d "{\"password\":\"$GUEST_PASS\"}" "$HOST/api/v0/auth/login?type=bearer" | jq -r .token)
+HAVE_GUEST=0
+[ -n "$GUEST_TOKEN" ] && [ "$GUEST_TOKEN" != "null" ] && HAVE_GUEST=1
+
+sleep 4
+
+# Save the pre-mutation state so we can restore everything at the
+# end. We only modify two fields (max_upload_kbps + autoconnect) so
+# the operator's daemon doesn't end the smoke in an unexpected state.
+_curl -H "Authorization: Bearer $ADMIN_TOKEN" "$HOST/api/v0/preferences"
+SAVED_MAX_UPLOAD=$(printf '%s' "$CURL_BODY" | jq -r '.connection.max_upload_kbps')
+SAVED_AUTOCONNECT=$(printf '%s' "$CURL_BODY" | jq -r '.connection.autoconnect')
+echo "    info: saved state max_upload_kbps=$SAVED_MAX_UPLOAD autoconnect=$SAVED_AUTOCONNECT"
+
+# --- 1. Auth + admin gate. -----------------------------------------
+_curl -X PATCH -H "Content-Type: application/json" \
+	-d '{"connection":{"max_upload_kbps":42}}' "$HOST/api/v0/preferences"
+_assert_status 401 "PATCH /preferences (no token) → 401"
+
+if [ "$HAVE_GUEST" = "1" ]; then
+	_curl -X PATCH -H "Authorization: Bearer $GUEST_TOKEN" \
+		-H "Content-Type: application/json" \
+		-d '{"connection":{"max_upload_kbps":42}}' "$HOST/api/v0/preferences"
+	_assert_status 403 "PATCH /preferences (guest) → 403"
+else
+	echo "    info: no guest pass; admin-gate skipped"
+fi
+
+# --- 2. PATCH numeric field — response + no-stale GET. -------------
+_curl -X PATCH -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{"connection":{"max_upload_kbps":42}}' "$HOST/api/v0/preferences"
+_assert_status 200 "PATCH max_upload_kbps=42 → 200"
+_assert_json_eq '.connection.max_upload_kbps' 42 \
+	'PATCH response.connection.max_upload_kbps == 42'
+
+# Immediate GET — no stale cache.
+_curl -H "Authorization: Bearer $ADMIN_TOKEN" "$HOST/api/v0/preferences"
+_assert_json_eq '.connection.max_upload_kbps' 42 \
+	'IMMEDIATE GET after PATCH shows max_upload_kbps=42 (no stale cache)'
+
+# --- 3. PATCH boolean field — bool tags need DETAIL_FULL on EC. ----
+_curl -X PATCH -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{"connection":{"autoconnect":false}}' "$HOST/api/v0/preferences"
+_assert_status 200 "PATCH autoconnect=false → 200"
+_assert_json_eq '.connection.autoconnect' false \
+	'PATCH response.connection.autoconnect == false'
+_curl -H "Authorization: Bearer $ADMIN_TOKEN" "$HOST/api/v0/preferences"
+_assert_json_eq '.connection.autoconnect' false \
+	'IMMEDIATE GET shows autoconnect=false (EC_DETAIL_FULL honored bool)'
+
+# Flip it back to verify the symmetric direction.
+_curl -X PATCH -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{"connection":{"autoconnect":true}}' "$HOST/api/v0/preferences"
+_assert_json_eq '.connection.autoconnect' true \
+	'PATCH autoconnect=true response shows autoconnect=true'
+
+# --- 4. Combined PATCH — multiple fields in one body. -------------
+_curl -X PATCH -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{"connection":{"max_upload_kbps":77,"autoconnect":false}}' \
+	"$HOST/api/v0/preferences"
+_assert_status 200 "PATCH combined (max_upload + autoconnect) → 200"
+_assert_json_eq '.connection.max_upload_kbps' 77    'combined PATCH response max_upload_kbps=77'
+_assert_json_eq '.connection.autoconnect'     false 'combined PATCH response autoconnect=false'
+_curl -H "Authorization: Bearer $ADMIN_TOKEN" "$HOST/api/v0/preferences"
+_assert_json_eq '.connection.max_upload_kbps' 77    'IMMEDIATE GET max_upload_kbps=77'
+_assert_json_eq '.connection.autoconnect'     false 'IMMEDIATE GET autoconnect=false'
+
+# --- 5. Error paths. -----------------------------------------------
+_curl -X PATCH -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{}' "$HOST/api/v0/preferences"
+_assert_status 400 "PATCH empty body → 400"
+
+_curl -X PATCH -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{"general":"not an object"}' "$HOST/api/v0/preferences"
+_assert_status 400 "PATCH general non-object → 400"
+
+_curl -X PATCH -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{"connection":{"max_upload_kbps":"forty-two"}}' "$HOST/api/v0/preferences"
+_assert_status 400 "PATCH max_upload_kbps as string → 400"
+
+_curl -X PATCH -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{"connection":{"tcp_port":99999}}' "$HOST/api/v0/preferences"
+_assert_status 400 "PATCH tcp_port out of range (>65535) → 400"
+
+_curl -X PATCH -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{"connection":{"autoconnect":"yes"}}' "$HOST/api/v0/preferences"
+_assert_status 400 "PATCH autoconnect as string → 400"
+
+_curl -X PATCH -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d 'not json' "$HOST/api/v0/preferences"
+_assert_status 400 "PATCH malformed JSON → 400"
+
+# --- 6. Restore pre-mutation state. --------------------------------
+_curl -X PATCH -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d "{\"connection\":{\"max_upload_kbps\":$SAVED_MAX_UPLOAD,\"autoconnect\":$SAVED_AUTOCONNECT}}" \
+	"$HOST/api/v0/preferences"
+_assert_status 200 "PATCH (restore pre-mutation state) → 200"
+_assert_json_eq '.connection.max_upload_kbps' "$SAVED_MAX_UPLOAD" \
+	'restored max_upload_kbps to saved value'
+_assert_json_eq '.connection.autoconnect' "$SAVED_AUTOCONNECT" \
+	'restored autoconnect to saved value'
+
+# --- Summary. -----------------------------------------------------
+echo
+if [ "$FAIL_COUNT" -eq 0 ]; then
+	echo "OK: $TEST_COUNT/$TEST_COUNT passed"
+	exit 0
+fi
+echo "FAIL: $FAIL_COUNT/$TEST_COUNT failed"
+exit 1
diff --git a/unittests/curl-tests/amuleapi/16-networks-connect.sh b/unittests/curl-tests/amuleapi/16-networks-connect.sh
new file mode 100755
index 0000000000..2e4103adfd
--- /dev/null
+++ b/unittests/curl-tests/amuleapi/16-networks-connect.sh
@@ -0,0 +1,197 @@
+#!/usr/bin/env bash
+#
+# amuleapi 16-networks-connect — connection control mutations.
+#
+# Endpoints:
+#   POST /api/v0/networks/connect       — EC_OP_CONNECT (all enabled
+#                                         nets) or one of
+#                                         EC_OP_SERVER_CONNECT / EC_OP_KAD_START
+#                                         when a network selector is passed
+#   POST /api/v0/networks/disconnect    — EC_OP_DISCONNECT (all nets)
+#   (Dedicated /api/v0/kad/{connect,disconnect} were dropped in
+#   favour of the network-selector form on /networks/*.)
+#   POST /api/v0/kad/bootstrap          — EC_OP_KAD_BOOTSTRAP_FROM_IP
+#       body: {ip: "1.2.3.4" | uint32, port: uint16}
+#
+# amuled's CONNECT/DISCONNECT return EC_OP_STRINGS with status
+# messages — the handler relays those into `response.message`.
+
+set -u
+set -o pipefail
+
+HOST=${HOST:-localhost:4713}
+ADMIN_PASS=${ADMIN_PASS:-adminpass}
+GUEST_PASS=${GUEST_PASS:-guestpass}
+
+FAIL_COUNT=0
+TEST_COUNT=0
+
+CURL_BODY_FILE=$(mktemp -t amuleapi_16_networks_connect_body.XXXXXX)
+trap 'rm -f "$CURL_BODY_FILE"' EXIT
+
+_die()  { echo "FATAL: $*" >&2; exit 2; }
+_pass() { TEST_COUNT=$((TEST_COUNT+1)); echo "  PASS  $1"; }
+_fail() {
+	TEST_COUNT=$((TEST_COUNT+1)); FAIL_COUNT=$((FAIL_COUNT+1))
+	echo "  FAIL  $1"
+	shift
+	for arg in "$@"; do echo "        $arg"; done
+}
+
+_curl() {
+	local resp
+	resp=$(curl -s --max-time 10 -o "$CURL_BODY_FILE" -w '%{http_code}' "$@") \
+		|| _die "curl invocation failed for $*"
+	CURL_STATUS=$resp
+	CURL_BODY=$(cat "$CURL_BODY_FILE")
+}
+
+_assert_status() {
+	local expected=$1 label=$2
+	if [ "$CURL_STATUS" = "$expected" ]; then
+		_pass "$label (HTTP $CURL_STATUS)"
+	else
+		_fail "$label" "expected HTTP $expected, got $CURL_STATUS" \
+			"body head: $(printf '%s' "$CURL_BODY" | head -c 200)"
+	fi
+}
+
+_assert_json_eq() {
+	local expr=$1 expected=$2 label=$3
+	local actual
+	actual=$(printf '%s' "$CURL_BODY" | jq -r "$expr" 2>/dev/null) \
+		|| _fail "$label" "body was not valid JSON" "body: $CURL_BODY"
+	if [ "$actual" = "$expected" ]; then
+		_pass "$label"
+	else
+		_fail "$label" "expected $expected, got $actual" "body: $CURL_BODY"
+	fi
+}
+
+if ! command -v jq >/dev/null 2>&1; then _die "jq is required."; fi
+if ! curl -s -o /dev/null --max-time 2 "$HOST/api/v0/version" 2>/dev/null; then
+	_die "amuleapi at $HOST is not reachable."
+fi
+
+echo "amuleapi 16-networks-connect smoke @ $HOST"
+
+ADMIN_TOKEN=$(curl -s -X POST -H "Content-Type: application/json" \
+	-d "{\"password\":\"$ADMIN_PASS\"}" "$HOST/api/v0/auth/login?type=bearer" | jq -r .token)
+[ -n "$ADMIN_TOKEN" ] && [ "$ADMIN_TOKEN" != "null" ] || _die "admin login failed"
+
+GUEST_TOKEN=$(curl -s -X POST -H "Content-Type: application/json" \
+	-d "{\"password\":\"$GUEST_PASS\"}" "$HOST/api/v0/auth/login?type=bearer" | jq -r .token)
+HAVE_GUEST=0
+[ -n "$GUEST_TOKEN" ] && [ "$GUEST_TOKEN" != "null" ] && HAVE_GUEST=1
+
+sleep 4
+
+# --- 1. Auth + admin gate. -----------------------------------------
+_curl -X POST "$HOST/api/v0/networks/disconnect"
+_assert_status 401 "POST /networks/disconnect (no token) → 401"
+
+if [ "$HAVE_GUEST" = "1" ]; then
+	_curl -X POST -H "Authorization: Bearer $GUEST_TOKEN" \
+		"$HOST/api/v0/networks/disconnect"
+	_assert_status 403 "POST /networks/disconnect (guest) → 403"
+fi
+
+# --- 2. networks/disconnect → 200 + message. -----------------------
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/networks/disconnect"
+_assert_status 200 "POST /networks/disconnect → 200"
+_assert_json_eq '.ok' true 'disconnect response.ok==true'
+
+# --- 3. networks/connect → 202 + message. --------------------------
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/networks/connect"
+_assert_status 202 "POST /networks/connect → 202"
+_assert_json_eq '.ok' true 'connect response.ok==true'
+_assert_json_eq '.message | type' string 'connect response carries .message'
+
+# --- 4. networks/{disconnect,connect} (Kad-only via selector). ----
+# The dedicated /kad/connect + /kad/disconnect endpoints were dropped
+# in favour of /networks/{connect,disconnect} with `{"network":"kad"}`.
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{"network":"kad"}' \
+	"$HOST/api/v0/networks/disconnect"
+_assert_status 200 "POST /networks/disconnect {network:kad} → 200"
+_assert_json_eq '.ok' true 'networks/disconnect(kad) response.ok==true'
+
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{"network":"kad"}' \
+	"$HOST/api/v0/networks/connect"
+_assert_status 202 "POST /networks/connect {network:kad} → 202"
+_assert_json_eq '.ok' true 'networks/connect(kad) response.ok==true'
+
+# ed2k-only selector should also round-trip via the network field.
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{"network":"ed2k"}' \
+	"$HOST/api/v0/networks/connect"
+_assert_status 202 "POST /networks/connect {network:ed2k} → 202"
+
+# Bogus selector → 400 on both directions.
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{"network":"wat"}' \
+	"$HOST/api/v0/networks/connect"
+_assert_status 400 "POST /networks/connect {network:wat} → 400"
+
+# --- 5. kad/bootstrap happy path + error paths. -------------------
+#
+# Bootstrap to a localhost dummy address — amuled doesn't validate
+# routability; the call always succeeds at the EC-handler level (the
+# actual Kad probe is fire-and-forget UDP).
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{"ip":"127.0.0.1","port":4672}' \
+	"$HOST/api/v0/kad/bootstrap"
+_assert_status 202 "POST /kad/bootstrap (dotted-quad) → 202"
+_assert_json_eq '.ok'   true   'kad/bootstrap response.ok==true'
+_assert_json_eq '.port' 4672   'kad/bootstrap response echoes port'
+
+# Uint32 IP form should also work.
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{"ip":2130706433,"port":4672}' \
+	"$HOST/api/v0/kad/bootstrap"
+_assert_status 202 "POST /kad/bootstrap (uint32 IP) → 202"
+
+# Error: missing port.
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{"ip":"127.0.0.1"}' "$HOST/api/v0/kad/bootstrap"
+_assert_status 400 "POST /kad/bootstrap (no port) → 400"
+
+# Error: bogus IP.
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{"ip":"not.an.ip.addr","port":4672}' "$HOST/api/v0/kad/bootstrap"
+_assert_status 400 "POST /kad/bootstrap (bad IP) → 400"
+
+# Error: port out of range.
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{"ip":"127.0.0.1","port":99999}' "$HOST/api/v0/kad/bootstrap"
+_assert_status 400 "POST /kad/bootstrap (port>65535) → 400"
+
+# --- 6. Method gates. ----------------------------------------------
+_curl -X GET -H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/networks/connect"
+_assert_status 405 "GET /networks/connect → 405"
+
+_curl -X DELETE -H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/kad/bootstrap"
+_assert_status 405 "DELETE /kad/bootstrap → 405"
+
+# --- Summary. -----------------------------------------------------
+echo
+if [ "$FAIL_COUNT" -eq 0 ]; then
+	echo "OK: $TEST_COUNT/$TEST_COUNT passed"
+	exit 0
+fi
+echo "FAIL: $FAIL_COUNT/$TEST_COUNT failed"
+exit 1
diff --git a/unittests/curl-tests/amuleapi/17-shared-priority-patch.sh b/unittests/curl-tests/amuleapi/17-shared-priority-patch.sh
new file mode 100755
index 0000000000..6e34404826
--- /dev/null
+++ b/unittests/curl-tests/amuleapi/17-shared-priority-patch.sh
@@ -0,0 +1,191 @@
+#!/usr/bin/env bash
+#
+# amuleapi 17-shared-priority-patch — PATCH /shared/{hash} priority.
+#
+# Endpoint:
+#   PATCH /api/v0/shared/{hash}
+#       body: {priority: <enum>}
+#
+# Priority enum mirrors the /shared GET shape (combined wire strings
+# including the *_auto variants):
+#   very_low | low | normal | high | release | auto
+#   very_low_auto | low_auto | normal_auto | high_auto | release_auto
+#
+# auto-priority is encoded amule-side as `prio + 10`; the handler
+# splits the wire string into the raw PR_* code + auto offset.
+
+set -u
+set -o pipefail
+
+HOST=${HOST:-localhost:4713}
+ADMIN_PASS=${ADMIN_PASS:-adminpass}
+GUEST_PASS=${GUEST_PASS:-guestpass}
+
+FAIL_COUNT=0
+TEST_COUNT=0
+
+CURL_BODY_FILE=$(mktemp -t amuleapi_17_shared_priority_patch_body.XXXXXX)
+trap 'rm -f "$CURL_BODY_FILE"' EXIT
+
+_die()  { echo "FATAL: $*" >&2; exit 2; }
+_pass() { TEST_COUNT=$((TEST_COUNT+1)); echo "  PASS  $1"; }
+_fail() {
+	TEST_COUNT=$((TEST_COUNT+1)); FAIL_COUNT=$((FAIL_COUNT+1))
+	echo "  FAIL  $1"
+	shift
+	for arg in "$@"; do echo "        $arg"; done
+}
+
+_curl() {
+	local resp
+	resp=$(curl -s --max-time 10 -o "$CURL_BODY_FILE" -w '%{http_code}' "$@") \
+		|| _die "curl invocation failed for $*"
+	CURL_STATUS=$resp
+	CURL_BODY=$(cat "$CURL_BODY_FILE")
+}
+
+_assert_status() {
+	local expected=$1 label=$2
+	if [ "$CURL_STATUS" = "$expected" ]; then
+		_pass "$label (HTTP $CURL_STATUS)"
+	else
+		_fail "$label" "expected HTTP $expected, got $CURL_STATUS" \
+			"body head: $(printf '%s' "$CURL_BODY" | head -c 200)"
+	fi
+}
+
+_assert_json_eq() {
+	local expr=$1 expected=$2 label=$3
+	local actual
+	actual=$(printf '%s' "$CURL_BODY" | jq -r "$expr" 2>/dev/null) \
+		|| _fail "$label" "body was not valid JSON" "body: $CURL_BODY"
+	if [ "$actual" = "$expected" ]; then
+		_pass "$label"
+	else
+		_fail "$label" "expected $expected, got $actual" "body: $CURL_BODY"
+	fi
+}
+
+if ! command -v jq >/dev/null 2>&1; then _die "jq is required."; fi
+if ! curl -s -o /dev/null --max-time 2 "$HOST/api/v0/version" 2>/dev/null; then
+	_die "amuleapi at $HOST is not reachable."
+fi
+
+echo "amuleapi 17-shared-priority-patch smoke @ $HOST"
+
+ADMIN_TOKEN=$(curl -s -X POST -H "Content-Type: application/json" \
+	-d "{\"password\":\"$ADMIN_PASS\"}" "$HOST/api/v0/auth/login?type=bearer" | jq -r .token)
+[ -n "$ADMIN_TOKEN" ] && [ "$ADMIN_TOKEN" != "null" ] || _die "admin login failed"
+
+GUEST_TOKEN=$(curl -s -X POST -H "Content-Type: application/json" \
+	-d "{\"password\":\"$GUEST_PASS\"}" "$HOST/api/v0/auth/login?type=bearer" | jq -r .token)
+HAVE_GUEST=0
+[ -n "$GUEST_TOKEN" ] && [ "$GUEST_TOKEN" != "null" ] && HAVE_GUEST=1
+
+sleep 4
+
+# Pick the first shared file for testing — order-independent across
+# operator's libraries. /shared is the broader surface (completed
+# knownfiles + downloading-and-shared partfiles per Phase 4f).
+_curl -H "Authorization: Bearer $ADMIN_TOKEN" "$HOST/api/v0/shared"
+COUNT=$(printf '%s' "$CURL_BODY" | jq '.shared | length')
+if [ "$COUNT" = "0" ]; then
+	echo "    info: no shared files; cannot exercise PATCH path"
+	_die "smoke needs at least one shared file"
+fi
+TEST_HASH=$(printf '%s' "$CURL_BODY" | jq -r '.shared[0].hash')
+SAVED_PRIORITY=$(printf '%s' "$CURL_BODY" | jq -r '.shared[0].priority')
+echo "    info: saved hash=$TEST_HASH priority=$SAVED_PRIORITY"
+
+# --- 1. Auth + admin gate. -----------------------------------------
+_curl -X PATCH -H "Content-Type: application/json" \
+	-d '{"priority":"high"}' "$HOST/api/v0/shared/$TEST_HASH"
+_assert_status 401 "PATCH /shared/{hash} (no token) → 401"
+
+if [ "$HAVE_GUEST" = "1" ]; then
+	_curl -X PATCH -H "Authorization: Bearer $GUEST_TOKEN" \
+		-H "Content-Type: application/json" \
+		-d '{"priority":"high"}' "$HOST/api/v0/shared/$TEST_HASH"
+	_assert_status 403 "PATCH /shared/{hash} (guest) → 403"
+fi
+
+# --- 2. PATCH priority each bare value + no-stale GET. ------------
+for p in low normal high release very_low; do
+	_curl -X PATCH -H "Authorization: Bearer $ADMIN_TOKEN" \
+		-H "Content-Type: application/json" \
+		-d "{\"priority\":\"$p\"}" "$HOST/api/v0/shared/$TEST_HASH"
+	_assert_status 200 "PATCH priority=$p → 200"
+	_assert_json_eq '.priority' "$p" "PATCH response shows priority=$p"
+
+	_curl -H "Authorization: Bearer $ADMIN_TOKEN" "$HOST/api/v0/shared"
+	OBS=$(printf '%s' "$CURL_BODY" \
+		| jq -r --arg h "$TEST_HASH" \
+		  '.shared[] | select(.hash == $h) | .priority')
+	if [ "$OBS" = "$p" ]; then
+		_pass "IMMEDIATE GET /shared shows priority=$p (no stale)"
+	else
+		_fail "IMMEDIATE GET /shared priority" \
+			"expected $p, got $OBS (stale cache)"
+	fi
+done
+
+# --- 3. PATCH auto variants. --------------------------------------
+# Pure "auto" amule resolves to a concrete derived enum (e.g.
+# "normal_auto" depending on the file's stats), so we don't pin it
+# to "auto" verbatim — just assert the response carries SOME *_auto
+# variant.
+for p in low_auto high_auto; do
+	_curl -X PATCH -H "Authorization: Bearer $ADMIN_TOKEN" \
+		-H "Content-Type: application/json" \
+		-d "{\"priority\":\"$p\"}" "$HOST/api/v0/shared/$TEST_HASH"
+	_assert_status 200 "PATCH priority=$p → 200"
+	_assert_json_eq '.priority' "$p" "PATCH response shows priority=$p"
+done
+# Bare "auto" → response should be an *_auto variant.
+_curl -X PATCH -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{"priority":"auto"}' "$HOST/api/v0/shared/$TEST_HASH"
+_assert_status 200 "PATCH priority=auto → 200"
+RESOLVED=$(printf '%s' "$CURL_BODY" | jq -r '.priority')
+case "$RESOLVED" in
+	auto|*_auto) _pass "PATCH priority=auto resolved to $RESOLVED (an auto variant)" ;;
+	*)           _fail "PATCH priority=auto" \
+	                   "expected an *_auto variant, got '$RESOLVED'" ;;
+esac
+
+# --- 4. Error paths. ----------------------------------------------
+_curl -X PATCH -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{"priority":"bogus"}' "$HOST/api/v0/shared/$TEST_HASH"
+_assert_status 400 "PATCH unknown priority enum → 400"
+
+_curl -X PATCH -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{}' "$HOST/api/v0/shared/$TEST_HASH"
+_assert_status 400 "PATCH empty body (no priority) → 400"
+
+_curl -X PATCH -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{"priority":"low"}' \
+	"$HOST/api/v0/shared/baadbaadbaadbaadbaadbaadbaadbaad"
+_assert_status 404 "PATCH unknown hash → 404"
+
+# --- 5. Method gate (POST/DELETE not allowed). --------------------
+_curl -X DELETE -H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/shared/$TEST_HASH"
+_assert_status 405 "DELETE /shared/{hash} → 405"
+
+# --- 6. Restore saved priority. -----------------------------------
+_curl -X PATCH -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d "{\"priority\":\"$SAVED_PRIORITY\"}" "$HOST/api/v0/shared/$TEST_HASH"
+_assert_status 200 "PATCH (restore saved priority) → 200"
+
+# --- Summary. -----------------------------------------------------
+echo
+if [ "$FAIL_COUNT" -eq 0 ]; then
+	echo "OK: $TEST_COUNT/$TEST_COUNT passed"
+	exit 0
+fi
+echo "FAIL: $FAIL_COUNT/$TEST_COUNT failed"
+exit 1
diff --git a/unittests/curl-tests/amuleapi/18-categories-crud.sh b/unittests/curl-tests/amuleapi/18-categories-crud.sh
new file mode 100755
index 0000000000..81b297d5e9
--- /dev/null
+++ b/unittests/curl-tests/amuleapi/18-categories-crud.sh
@@ -0,0 +1,218 @@
+#!/usr/bin/env bash
+#
+# amuleapi 18-categories-crud — categories CRUD.
+#
+# Endpoints:
+#   POST   /api/v0/categories             — create
+#       body: {name, path?, comment?, color?, priority?}
+#   PATCH  /api/v0/categories/{index}     — update
+#       body: any subset of {name, path, comment, color, priority}
+#   DELETE /api/v0/categories/{index}     — remove
+#
+# The default (index=0) "All" category cannot be deleted —
+# DELETE /categories/0 returns 400. Custom categories are 1..255.
+
+set -u
+set -o pipefail
+
+HOST=${HOST:-localhost:4713}
+ADMIN_PASS=${ADMIN_PASS:-adminpass}
+GUEST_PASS=${GUEST_PASS:-guestpass}
+
+TEST_NAME="18-categories-crud-smoke-cat"
+TEST_PATH="/tmp/18-categories-crud-cat-dir"
+
+FAIL_COUNT=0
+TEST_COUNT=0
+
+CURL_BODY_FILE=$(mktemp -t amuleapi_18_categories_crud_body.XXXXXX)
+trap 'rm -f "$CURL_BODY_FILE"' EXIT
+
+_die()  { echo "FATAL: $*" >&2; exit 2; }
+_pass() { TEST_COUNT=$((TEST_COUNT+1)); echo "  PASS  $1"; }
+_fail() {
+	TEST_COUNT=$((TEST_COUNT+1)); FAIL_COUNT=$((FAIL_COUNT+1))
+	echo "  FAIL  $1"
+	shift
+	for arg in "$@"; do echo "        $arg"; done
+}
+
+_curl() {
+	local resp
+	resp=$(curl -s --max-time 10 -o "$CURL_BODY_FILE" -w '%{http_code}' "$@") \
+		|| _die "curl invocation failed for $*"
+	CURL_STATUS=$resp
+	CURL_BODY=$(cat "$CURL_BODY_FILE")
+}
+
+_assert_status() {
+	local expected=$1 label=$2
+	if [ "$CURL_STATUS" = "$expected" ]; then
+		_pass "$label (HTTP $CURL_STATUS)"
+	else
+		_fail "$label" "expected HTTP $expected, got $CURL_STATUS" \
+			"body head: $(printf '%s' "$CURL_BODY" | head -c 200)"
+	fi
+}
+
+_assert_json_eq() {
+	local expr=$1 expected=$2 label=$3
+	local actual
+	actual=$(printf '%s' "$CURL_BODY" | jq -r "$expr" 2>/dev/null) \
+		|| _fail "$label" "body was not valid JSON" "body: $CURL_BODY"
+	if [ "$actual" = "$expected" ]; then
+		_pass "$label"
+	else
+		_fail "$label" "expected $expected, got $actual" "body: $CURL_BODY"
+	fi
+}
+
+if ! command -v jq >/dev/null 2>&1; then _die "jq is required."; fi
+if ! curl -s -o /dev/null --max-time 2 "$HOST/api/v0/version" 2>/dev/null; then
+	_die "amuleapi at $HOST is not reachable."
+fi
+
+mkdir -p "$TEST_PATH"
+
+echo "amuleapi 18-categories-crud smoke @ $HOST"
+
+ADMIN_TOKEN=$(curl -s -X POST -H "Content-Type: application/json" \
+	-d "{\"password\":\"$ADMIN_PASS\"}" "$HOST/api/v0/auth/login?type=bearer" | jq -r .token)
+[ -n "$ADMIN_TOKEN" ] && [ "$ADMIN_TOKEN" != "null" ] || _die "admin login failed"
+
+GUEST_TOKEN=$(curl -s -X POST -H "Content-Type: application/json" \
+	-d "{\"password\":\"$GUEST_PASS\"}" "$HOST/api/v0/auth/login?type=bearer" | jq -r .token)
+HAVE_GUEST=0
+[ -n "$GUEST_TOKEN" ] && [ "$GUEST_TOKEN" != "null" ] && HAVE_GUEST=1
+
+sleep 4
+
+# --- 1. Auth + admin gate. -----------------------------------------
+_curl -X POST -H "Content-Type: application/json" \
+	-d "{\"name\":\"$TEST_NAME\"}" "$HOST/api/v0/categories"
+_assert_status 401 "POST /categories (no token) → 401"
+
+_curl -X PATCH -H "Content-Type: application/json" \
+	-d '{"name":"x"}' "$HOST/api/v0/categories/1"
+_assert_status 401 "PATCH /categories/{idx} (no token) → 401"
+
+_curl -X DELETE "$HOST/api/v0/categories/1"
+_assert_status 401 "DELETE /categories/{idx} (no token) → 401"
+
+if [ "$HAVE_GUEST" = "1" ]; then
+	_curl -X POST -H "Authorization: Bearer $GUEST_TOKEN" \
+		-H "Content-Type: application/json" \
+		-d "{\"name\":\"$TEST_NAME\"}" "$HOST/api/v0/categories"
+	_assert_status 403 "POST /categories (guest) → 403"
+fi
+
+# --- 2. POST /categories (create). --------------------------------
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d "{\"name\":\"$TEST_NAME\",\"path\":\"$TEST_PATH\",\"comment\":\"18-categories-crud test\",\"priority\":\"high\"}" \
+	"$HOST/api/v0/categories"
+_assert_status 201 "POST /categories (create) → 201"
+_assert_json_eq '.ok'   true        'create response.ok==true'
+_assert_json_eq '.name' "$TEST_NAME" 'create response echoes name'
+
+NEW_IDX=$(printf '%s' "$CURL_BODY" | jq -r '.index')
+if [ -n "$NEW_IDX" ] && [ "$NEW_IDX" != "null" ]; then
+	_pass "create response includes assigned index ($NEW_IDX)"
+else
+	_die "could not parse new category index from create response"
+fi
+
+# Verify by GET /categories.
+_curl -H "Authorization: Bearer $ADMIN_TOKEN" "$HOST/api/v0/categories"
+LOOKUP=$(printf '%s' "$CURL_BODY" \
+	| jq --arg n "$TEST_NAME" \
+	  '[.categories[] | select(.name == $n)] | first')
+if [ "$LOOKUP" != "null" ]; then
+	_pass "Created category surfaces in /categories list"
+else
+	_fail "Created category lookup" \
+		"could not find $TEST_NAME in /categories list"
+fi
+
+# --- 3. POST error paths. -----------------------------------------
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{}' "$HOST/api/v0/categories"
+_assert_status 400 "POST /categories (no name) → 400"
+
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d "{\"name\":\"x\",\"priority\":\"bogus\"}" "$HOST/api/v0/categories"
+_assert_status 400 "POST /categories (bad priority enum) → 400"
+
+# --- 4. PATCH /categories/{idx}. ----------------------------------
+_curl -X PATCH -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{"comment":"updated by 18-categories-crud","priority":"low"}' \
+	"$HOST/api/v0/categories/$NEW_IDX"
+_assert_status 200 "PATCH /categories/$NEW_IDX → 200"
+_assert_json_eq '.comment'  'updated by 18-categories-crud' 'PATCH response shows new comment'
+_assert_json_eq '.priority' low                  'PATCH response shows priority=low'
+
+# Immediate GET (no-stale).
+_curl -H "Authorization: Bearer $ADMIN_TOKEN" "$HOST/api/v0/categories"
+OBS_COMMENT=$(printf '%s' "$CURL_BODY" \
+	| jq -r --arg n "$TEST_NAME" \
+	  '.categories[] | select(.name == $n) | .comment')
+if [ "$OBS_COMMENT" = "updated by 18-categories-crud" ]; then
+	_pass "IMMEDIATE GET /categories shows updated comment (no stale)"
+else
+	_fail "GET /categories staleness after PATCH" \
+		"expected 'updated by 18-categories-crud', got '$OBS_COMMENT'"
+fi
+
+# --- 5. PATCH error paths. ----------------------------------------
+_curl -X PATCH -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{"priority":"bogus"}' "$HOST/api/v0/categories/$NEW_IDX"
+_assert_status 400 "PATCH /categories bogus enum → 400"
+
+_curl -X PATCH -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{"name":"unknown"}' "$HOST/api/v0/categories/199"
+_assert_status 404 "PATCH /categories unknown index → 404"
+
+_curl -X PATCH -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{"name":"x"}' "$HOST/api/v0/categories/not-a-number"
+_assert_status 400 "PATCH /categories non-numeric index → 400"
+
+# --- 6. DELETE happy path + cannot-delete-default + no-stale. ----
+_curl -X DELETE -H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/categories/0"
+_assert_status 400 "DELETE /categories/0 (default) → 400"
+
+_curl -X DELETE -H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/categories/$NEW_IDX"
+_assert_status 200 "DELETE /categories/$NEW_IDX → 200"
+_assert_json_eq '.ok'    true       'DELETE response.ok==true'
+_assert_json_eq '.index' "$NEW_IDX" 'DELETE response echoes index'
+
+_curl -H "Authorization: Bearer $ADMIN_TOKEN" "$HOST/api/v0/categories"
+STILL=$(printf '%s' "$CURL_BODY" \
+	| jq --arg n "$TEST_NAME" \
+	  '[.categories[] | select(.name == $n)] | length')
+if [ "$STILL" = "0" ]; then
+	_pass "Deleted category gone from /categories list (no stale)"
+else
+	_fail "/categories staleness after DELETE" \
+		"$TEST_NAME still present after DELETE"
+fi
+
+_curl -X DELETE -H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/categories/$NEW_IDX"
+_assert_status 404 "DELETE same index twice → 404"
+
+# --- Summary. -----------------------------------------------------
+echo
+if [ "$FAIL_COUNT" -eq 0 ]; then
+	echo "OK: $TEST_COUNT/$TEST_COUNT passed"
+	exit 0
+fi
+echo "FAIL: $FAIL_COUNT/$TEST_COUNT failed"
+exit 1
diff --git a/unittests/curl-tests/amuleapi/19-search.sh b/unittests/curl-tests/amuleapi/19-search.sh
new file mode 100755
index 0000000000..e53ae12c2f
--- /dev/null
+++ b/unittests/curl-tests/amuleapi/19-search.sh
@@ -0,0 +1,351 @@
+#!/usr/bin/env bash
+#
+# amuleapi 19-search — search.
+#
+# Endpoints:
+#   POST /api/v0/search                                   — EC_OP_SEARCH_START
+#       body: {query, type?, file_type?, extension?,
+#              min_size?, max_size?, min_avail?}
+#   POST /api/v0/search/stop                              — EC_OP_SEARCH_STOP
+#   GET  /api/v0/search/results                            — read accumulated
+#   POST /api/v0/search/results/{hash}/download           — EC_OP_DOWNLOAD_SEARCH_RESULT
+#       body: {category?: uint8} (optional)
+#
+# /search/results is no longer a per-GET fetch — POST /search marks
+# the search active in state and the refresher polls amuled every
+# tick while it stays active. GET /search/results reads straight
+# from that state, so subsequent polls already see the fresh query's
+# growing results without any cache coordination.
+#
+# amuled's SEARCH_START is async: results trickle in from servers /
+# Kad over the next several seconds. Smoke polls /search/results with
+# bounded retries (up to ~10 s for a global search to harvest results).
+#
+# Important: this smoke depends on the operator's amuled being
+# connected to ed2k servers (for global search) and/or Kad. A
+# fully-disconnected daemon will see 0 results — the smoke skips the
+# result-shape checks in that case and only exercises the API surface.
+
+set -u
+set -o pipefail
+
+HOST=${HOST:-localhost:4713}
+ADMIN_PASS=${ADMIN_PASS:-adminpass}
+GUEST_PASS=${GUEST_PASS:-guestpass}
+
+# A query likely to return results on any operator's daemon connected
+# to ed2k. "ubuntu" is a safe choice — well-seeded across the network.
+TEST_QUERY="ubuntu"
+
+FAIL_COUNT=0
+TEST_COUNT=0
+
+CURL_BODY_FILE=$(mktemp -t amuleapi_19_search_body.XXXXXX)
+trap 'rm -f "$CURL_BODY_FILE"' EXIT
+
+_die()  { echo "FATAL: $*" >&2; exit 2; }
+_pass() { TEST_COUNT=$((TEST_COUNT+1)); echo "  PASS  $1"; }
+_fail() {
+	TEST_COUNT=$((TEST_COUNT+1)); FAIL_COUNT=$((FAIL_COUNT+1))
+	echo "  FAIL  $1"
+	shift
+	for arg in "$@"; do echo "        $arg"; done
+}
+
+_curl() {
+	local resp
+	resp=$(curl -s --max-time 10 -o "$CURL_BODY_FILE" -w '%{http_code}' "$@") \
+		|| _die "curl invocation failed for $*"
+	CURL_STATUS=$resp
+	CURL_BODY=$(cat "$CURL_BODY_FILE")
+}
+
+_assert_status() {
+	local expected=$1 label=$2
+	if [ "$CURL_STATUS" = "$expected" ]; then
+		_pass "$label (HTTP $CURL_STATUS)"
+	else
+		_fail "$label" "expected HTTP $expected, got $CURL_STATUS" \
+			"body head: $(printf '%s' "$CURL_BODY" | head -c 200)"
+	fi
+}
+
+_assert_json_eq() {
+	local expr=$1 expected=$2 label=$3
+	local actual
+	actual=$(printf '%s' "$CURL_BODY" | jq -r "$expr" 2>/dev/null) \
+		|| _fail "$label" "body was not valid JSON" "body: $CURL_BODY"
+	if [ "$actual" = "$expected" ]; then
+		_pass "$label"
+	else
+		_fail "$label" "expected $expected, got $actual" "body: $CURL_BODY"
+	fi
+}
+
+if ! command -v jq >/dev/null 2>&1; then _die "jq is required."; fi
+if ! curl -s -o /dev/null --max-time 2 "$HOST/api/v0/version" 2>/dev/null; then
+	_die "amuleapi at $HOST is not reachable."
+fi
+
+echo "amuleapi 19-search smoke @ $HOST"
+
+ADMIN_TOKEN=$(curl -s -X POST -H "Content-Type: application/json" \
+	-d "{\"password\":\"$ADMIN_PASS\"}" "$HOST/api/v0/auth/login?type=bearer" | jq -r .token)
+[ -n "$ADMIN_TOKEN" ] && [ "$ADMIN_TOKEN" != "null" ] || _die "admin login failed"
+
+GUEST_TOKEN=$(curl -s -X POST -H "Content-Type: application/json" \
+	-d "{\"password\":\"$GUEST_PASS\"}" "$HOST/api/v0/auth/login?type=bearer" | jq -r .token)
+HAVE_GUEST=0
+[ -n "$GUEST_TOKEN" ] && [ "$GUEST_TOKEN" != "null" ] && HAVE_GUEST=1
+
+sleep 4
+
+# --- 1. Auth + admin gate. -----------------------------------------
+_curl -X POST -H "Content-Type: application/json" \
+	-d "{\"query\":\"$TEST_QUERY\"}" "$HOST/api/v0/search"
+_assert_status 401 "POST /search (no token) → 401"
+
+_curl -X POST "$HOST/api/v0/search/stop"
+_assert_status 401 "POST /search/stop (no token) → 401"
+
+_curl -X POST "$HOST/api/v0/search/results/baadbaadbaadbaadbaadbaadbaadbaad/download"
+_assert_status 401 "POST /search/results/{hash}/download (no token) → 401"
+
+if [ "$HAVE_GUEST" = "1" ]; then
+	_curl -X POST -H "Authorization: Bearer $GUEST_TOKEN" \
+		-H "Content-Type: application/json" \
+		-d "{\"query\":\"$TEST_QUERY\"}" "$HOST/api/v0/search"
+	_assert_status 403 "POST /search (guest) → 403"
+fi
+
+# --- 2. POST /search error paths. ----------------------------------
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{}' "$HOST/api/v0/search"
+_assert_status 400 "POST /search (no query) → 400"
+
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{"query":""}' "$HOST/api/v0/search"
+_assert_status 400 "POST /search (empty query) → 400"
+
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d "{\"query\":\"$TEST_QUERY\",\"type\":\"bogus\"}" "$HOST/api/v0/search"
+_assert_status 400 "POST /search (bad type enum) → 400"
+
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d "{\"query\":\"$TEST_QUERY\",\"min_size\":-1}" "$HOST/api/v0/search"
+_assert_status 400 "POST /search (negative min_size) → 400"
+
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d 'not json' "$HOST/api/v0/search"
+_assert_status 400 "POST /search (malformed JSON) → 400"
+
+# --- 3. POST /search happy + results-reset observable. ---------
+#
+# amuled wipes its searchlist on SEARCH_START (ExternalConn.cpp:1437),
+# and amuleapi's MarkSearchStarted wipes m_search alongside it so the
+# pre-POST results don't bleed into the new query. Step 4 below proves
+# the reset is observable: the polling loop must see the new query's
+# results fill up rather than the prior query's tail.
+_curl -H "Authorization: Bearer $ADMIN_TOKEN" "$HOST/api/v0/search/results"
+_assert_status 200 "GET /search/results (baseline before POST) → 200"
+
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d "{\"query\":\"$TEST_QUERY\",\"type\":\"global\"}" "$HOST/api/v0/search"
+_assert_status 202 "POST /search (query=$TEST_QUERY, type=global) → 202"
+_assert_json_eq '.ok'    true         'POST /search response.ok==true'
+_assert_json_eq '.query' "$TEST_QUERY" 'POST /search echoes query'
+
+# --- 3.5 Regression: progress shouldn't claim finished right after POST. -
+# amuled briefly reports raw=100 in the "queue-empty-at-start" window
+# before the global-search timer populates m_serverQueue; if amuleapi
+# trusted that raw value naively, GET /search/results right after POST
+# would (incorrectly) say {progress:{percent:100, state:"finished"}}
+# with results=[]. The refresher's state machine masks that window —
+# this asserts the mask is in force.
+_curl -H "Authorization: Bearer $ADMIN_TOKEN" "$HOST/api/v0/search/results"
+_assert_status 200 "GET /search/results immediately after POST → 200"
+_assert_json_eq '.progress.state' running 'progress.state is "running" after POST /search'
+_assert_json_eq '.progress.kind | type' string 'progress.kind is a string'
+
+# --- 4. Poll /search/results until we get hits (max ~10 s). -------
+RESULT_HASH=""
+for _ in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50; do
+	_curl -H "Authorization: Bearer $ADMIN_TOKEN" "$HOST/api/v0/search/results"
+	N=$(printf '%s' "$CURL_BODY" | jq '.results | length')
+	if [ "$N" -gt 0 ]; then
+		RESULT_HASH=$(printf '%s' "$CURL_BODY" | jq -r '.results[0].hash')
+		break
+	fi
+	sleep 0.2
+done
+
+if [ -n "$RESULT_HASH" ]; then
+	_pass "Search returned >0 results within 10 s ($N entries; sample hash $RESULT_HASH)"
+
+	# Per-result shape sanity.
+	_curl -H "Authorization: Bearer $ADMIN_TOKEN" "$HOST/api/v0/search/results"
+	_assert_json_eq '.results[0].hash | length' 32     '/search/results[0].hash is 32-char hex'
+	_assert_json_eq '.results[0].name | type'   string '/search/results[0].name is string'
+	_assert_json_eq '.results[0].size | type'   number '/search/results[0].size is numeric'
+
+	# progress envelope. `progress` exists on every GET /search/results
+	# response (even before any POST /search). `state` is canonical
+	# (running | finished | idle) and replaces the old complete/active
+	# booleans. Once we have results, state is "running" (still polling)
+	# or "finished" (percent == 100).
+	_assert_json_eq '.progress.percent | type' number 'search progress.percent is numeric'
+	_assert_json_eq '.progress.state | type'   string 'search progress.state is a string'
+	_assert_json_eq '[.progress.state] | inside(["running","finished","idle"])' \
+		true 'search progress.state is one of running/finished/idle'
+	_assert_json_eq '.progress.percent >= 0 and .progress.percent <= 100' \
+		true 'search progress.percent stays in [0, 100]'
+else
+	echo "    info: 0 search results after 10 s — daemon may not be connected to ed2k/kad"
+	echo "    info: skipping /search/results/{hash}/download path (no hash to target)"
+fi
+
+# --- 5. POST /search/stop. ----------------------------------------
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/search/stop"
+_assert_status 200 "POST /search/stop → 200"
+_assert_json_eq '.ok' true 'search/stop response.ok==true'
+
+# --- 6. POST /search/results/{hash}/download — happy + cleanup. --
+if [ -n "$RESULT_HASH" ]; then
+	_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+		-H "Content-Type: application/json" \
+		-d '{"category":0}' \
+		"$HOST/api/v0/search/results/$RESULT_HASH/download"
+	_assert_status 202 "POST /search/results/{hash}/download → 202"
+	_assert_json_eq '.ok'       true         'download response.ok==true'
+	_assert_json_eq '.hash'     "$RESULT_HASH" 'download response echoes hash'
+	_assert_json_eq '.category' 0            'download response category=0'
+
+	# Empty-body POST should also succeed (category defaults to 0).
+	# But first DELETE the just-created download so we don't trip
+	# "already in queue".
+	_curl -X DELETE -H "Authorization: Bearer $ADMIN_TOKEN" \
+		"$HOST/api/v0/downloads/$RESULT_HASH"
+	# 200 if found, 404 if already evicted by amuled — either is OK.
+	if [ "$CURL_STATUS" = "200" ] || [ "$CURL_STATUS" = "404" ]; then
+		_pass "Cleanup: DELETE /downloads/{result hash} → $CURL_STATUS"
+	else
+		_fail "Cleanup DELETE" "unexpected status $CURL_STATUS"
+	fi
+fi
+
+# --- 7. POST /search/results/{hash}/download error paths. --------
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{}' "$HOST/api/v0/search/results/not-32-hex-chars/download"
+_assert_status 400 "POST download (bad hash format) → 400"
+
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{"category":300}' \
+	"$HOST/api/v0/search/results/baadbaadbaadbaadbaadbaadbaadbaad/download"
+_assert_status 400 "POST download (category out of range) → 400"
+
+# Unknown hash that's well-formed (32 hex chars) → amuled rejection.
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d '{}' "$HOST/api/v0/search/results/baadbaadbaadbaadbaadbaadbaadbaad/download"
+# amuled may either reject (400 amuled_rejected) or silently accept
+# the request and never instantiate the partfile — both wire shapes
+# have been observed; accept either.
+if [ "$CURL_STATUS" = "400" ] || [ "$CURL_STATUS" = "202" ]; then
+	_pass "POST download (well-formed unknown hash) → $CURL_STATUS"
+else
+	_fail "POST download unknown hash" \
+		"expected 400 or 202, got $CURL_STATUS"
+fi
+
+# --- 8. Method gates. ---------------------------------------------
+_curl -X GET -H "Authorization: Bearer $ADMIN_TOKEN" "$HOST/api/v0/search"
+_assert_status 405 "GET /search → 405"
+
+_curl -X PATCH -H "Authorization: Bearer $ADMIN_TOKEN" "$HOST/api/v0/search/stop"
+_assert_status 405 "PATCH /search/stop → 405"
+
+# --- 9. Kad search progress ramp. ---------------------------------
+# Kad has no measurable progress, so amuled synthesises a cosmetic
+# time-ramp from the fixed keyword-search lifetime (SEARCHKEYWORD_LIFETIME,
+# 45 s) and ships it in EC_TAG_SEARCH_LIFECYCLE_PERCENT; amuleapi
+# surfaces it verbatim as progress.percent. Assert the ramp climbs over
+# time and stays capped at 99 while running — only the authoritative
+# finished edge reaches 100, so the bar can never claim completion
+# early. Skips the ramp assertions if amuled isn't connected to Kad
+# (the search never goes "running").
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d "{\"query\":\"$TEST_QUERY\",\"type\":\"kad\"}" "$HOST/api/v0/search"
+_assert_status 202 "POST /search type=kad → 202"
+
+KAD_STATES=""; KAD_PCTS=""; SAW_RUNNING_KAD=0
+for _ in 1 2 3 4 5 6; do
+	_curl -H "Authorization: Bearer $ADMIN_TOKEN" "$HOST/api/v0/search/results"
+	ST=$(printf '%s' "$CURL_BODY" | jq -r '.progress.state')
+	KD=$(printf '%s' "$CURL_BODY" | jq -r '.progress.kind')
+	PC=$(printf '%s' "$CURL_BODY" | jq -r '.progress.percent')
+	KAD_STATES="$KAD_STATES $ST"; KAD_PCTS="$KAD_PCTS $PC"
+	if [ "$ST" = "running" ] && [ "$KD" = "kad" ]; then SAW_RUNNING_KAD=1; fi
+	sleep 2
+done
+echo "    kad samples: states=[$KAD_STATES ] percents=[$KAD_PCTS ]"
+
+if [ "$SAW_RUNNING_KAD" -eq 0 ]; then
+	echo "    info: Kad search never went 'running' — amuled likely not"
+	echo "    info: connected to Kad; skipping ramp assertions."
+else
+	CAP_OK=1; MONO=1; PREV=-1; FIRST_RUN=""; LAST_RUN=""; SAW_FINISHED=0
+	set -- $KAD_PCTS; KAD_PC_ARR=("$@")
+	idx=0
+	for st in $KAD_STATES; do
+		pc=${KAD_PC_ARR[$idx]}
+		if [ "$pc" -lt "$PREV" ] 2>/dev/null; then MONO=0; fi
+		PREV=$pc
+		if { [ "$pc" -lt 0 ] || [ "$pc" -gt 100 ]; } 2>/dev/null; then CAP_OK=0; fi
+		if [ "$st" = "running" ]; then
+			if [ "$pc" -gt 99 ] 2>/dev/null; then CAP_OK=0; fi
+			[ -z "$FIRST_RUN" ] && FIRST_RUN=$pc
+			LAST_RUN=$pc
+		fi
+		[ "$st" = "finished" ] && SAW_FINISHED=1
+		idx=$((idx+1))
+	done
+
+	if [ "$CAP_OK" -eq 1 ]; then
+		_pass "Kad running percent capped at 99 and within [0,100]"
+	else
+		_fail "Kad percent cap" "states=[$KAD_STATES ] percents=[$KAD_PCTS ]"
+	fi
+	if [ "$MONO" -eq 1 ]; then
+		_pass "Kad percent monotonic non-decreasing"
+	else
+		_fail "Kad percent monotonic" "percents went backwards: [$KAD_PCTS ]"
+	fi
+	if [ "$SAW_FINISHED" -eq 1 ] || \
+	   { [ -n "$FIRST_RUN" ] && [ -n "$LAST_RUN" ] && [ "$LAST_RUN" -gt "$FIRST_RUN" ] 2>/dev/null; }; then
+		_pass "Kad ramp advanced over time (first=$FIRST_RUN last=$LAST_RUN finished=$SAW_FINISHED)"
+	else
+		_fail "Kad ramp advance" \
+			"percent did not climb and search never finished: first=$FIRST_RUN last=$LAST_RUN states=[$KAD_STATES ]"
+	fi
+fi
+
+curl -s -X POST -H "Authorization: Bearer $ADMIN_TOKEN" "$HOST/api/v0/search/stop" > /dev/null 2>&1
+
+# --- Summary. -----------------------------------------------------
+echo
+if [ "$FAIL_COUNT" -eq 0 ]; then
+	echo "OK: $TEST_COUNT/$TEST_COUNT passed"
+	exit 0
+fi
+echo "FAIL: $FAIL_COUNT/$TEST_COUNT failed"
+exit 1
diff --git a/unittests/curl-tests/amuleapi/20-etag-conditional-get.sh b/unittests/curl-tests/amuleapi/20-etag-conditional-get.sh
new file mode 100755
index 0000000000..5c8f81675b
--- /dev/null
+++ b/unittests/curl-tests/amuleapi/20-etag-conditional-get.sh
@@ -0,0 +1,306 @@
+#!/usr/bin/env bash
+#
+# amuleapi 20-etag-conditional-get — ETag conditional GET.
+#
+# Wire contract:
+#   * Every GET / HEAD that returns 200 carries an `ETag: "<hex>"`
+#     header. The hex is a SHA-256 of the response body truncated to
+#     8 bytes (16 hex chars) — short enough to keep header overhead
+#     small, with 64 bits of collision resistance.
+#   * The server honors `If-None-Match` in four shapes:
+#     - `"<hex>"`        — RFC 7232 §2.3 canonical (quoted)
+#     - `<hex>`          — bare hex (backward-compat for non-canonical clients)
+#     - `W/"<hex>"`      — weak validator
+#     - `*`              — wildcard match-any-existing-representation
+#     - comma-separated list of any of the above
+#   * On a match, the server returns 304 Not Modified with no body but
+#     WITH the ETag header preserved (RFC §4.1 — clients use it to
+#     re-stamp the cached representation).
+#   * Mutations (POST / PATCH / DELETE) are passed through unchanged.
+#     If-None-Match on a mutation is ignored — the operation always
+#     runs and its response always lands. Phase 5's mutation contract
+#     would otherwise silently no-op on retries.
+#   * HEAD returns 200 + ETag + empty body (the GET path's body is
+#     stripped). HEAD also honors If-None-Match for cache validation.
+
+set -u
+set -o pipefail
+
+HOST=${HOST:-localhost:4713}
+ADMIN_PASS=${ADMIN_PASS:-adminpass}
+
+FAIL_COUNT=0
+TEST_COUNT=0
+
+CURL_BODY_FILE=$(mktemp -t amuleapi_20_etag_conditional_get_body.XXXXXX)
+CURL_HEAD_FILE=$(mktemp -t amuleapi_20_etag_conditional_get_head.XXXXXX)
+trap 'rm -f "$CURL_BODY_FILE" "$CURL_HEAD_FILE"' EXIT
+
+_die()  { echo "FATAL: $*" >&2; exit 2; }
+_pass() { TEST_COUNT=$((TEST_COUNT+1)); echo "  PASS  $1"; }
+_fail() {
+	TEST_COUNT=$((TEST_COUNT+1)); FAIL_COUNT=$((FAIL_COUNT+1))
+	echo "  FAIL  $1"
+	shift
+	for arg in "$@"; do echo "        $arg"; done
+}
+
+# Capture both status + headers. Stores HTTP status in CURL_STATUS,
+# response body in CURL_BODY, and the raw header dump in CURL_HEAD.
+# Empties both output files before invoking curl — curl leaves the
+# -o target untruncated on 304 Not Modified (no body to write), so a
+# follow-up read would see whatever the PREVIOUS request wrote.
+_curl() {
+	: > "$CURL_BODY_FILE"
+	: > "$CURL_HEAD_FILE"
+	local resp
+	resp=$(curl -s --max-time 10 -o "$CURL_BODY_FILE" \
+		-D "$CURL_HEAD_FILE" -w '%{http_code}' "$@") \
+		|| _die "curl invocation failed for $*"
+	CURL_STATUS=$resp
+	CURL_BODY=$(cat "$CURL_BODY_FILE")
+	CURL_HEAD=$(cat "$CURL_HEAD_FILE")
+}
+
+_assert_status() {
+	local expected=$1 label=$2
+	if [ "$CURL_STATUS" = "$expected" ]; then
+		_pass "$label (HTTP $CURL_STATUS)"
+	else
+		_fail "$label" "expected HTTP $expected, got $CURL_STATUS" \
+			"body head: $(printf '%s' "$CURL_BODY" | head -c 200)"
+	fi
+}
+
+# Extract the ETag header value from the captured response (with
+# quotes intact). Returns empty string if absent. Uses sed instead
+# of awk because BSD awk (macOS default) doesn't support IGNORECASE.
+_get_etag() {
+	printf '%s' "$CURL_HEAD" \
+		| sed -n 's/^[Ee][Tt][Aa][Gg]:[[:space:]]*\([^[:cntrl:]]*\).*/\1/p' \
+		| head -1
+}
+
+if ! command -v jq >/dev/null 2>&1; then _die "jq is required."; fi
+if ! curl -s -o /dev/null --max-time 2 "$HOST/api/v0/version" 2>/dev/null; then
+	_die "amuleapi at $HOST is not reachable."
+fi
+
+echo "amuleapi 20-etag-conditional-get smoke @ $HOST"
+
+ADMIN_TOKEN=$(curl -s -X POST -H "Content-Type: application/json" \
+	-d "{\"password\":\"$ADMIN_PASS\"}" "$HOST/api/v0/auth/login?type=bearer" | jq -r .token)
+[ -n "$ADMIN_TOKEN" ] && [ "$ADMIN_TOKEN" != "null" ] || _die "admin login failed"
+
+sleep 4
+
+# --- 1. GET /version stamps ETag header. ---------------------------
+#
+# /version is the smallest, most stable response — perfect for ETag
+# regression because the digest stays constant across daemon
+# restarts (only changes when the build's VERSION macro flips).
+_curl -H "Authorization: Bearer $ADMIN_TOKEN" "$HOST/api/v0/version"
+_assert_status 200 "GET /version → 200"
+
+ETAG=$(_get_etag)
+if [ -n "$ETAG" ]; then
+	_pass "GET /version carries ETag header (value: $ETAG)"
+else
+	_fail "GET /version ETag" "ETag header absent"
+	_die "cannot continue without an ETag value"
+fi
+
+# ETag must be quoted per RFC §2.3.
+case "$ETAG" in
+	\"*\") _pass "ETag value is quoted (RFC 7232 §2.3)" ;;
+	*)     _fail "ETag quoting" "expected \"<hex>\", got $ETAG" ;;
+esac
+
+# Extract the bare hex (strip outer quotes).
+BARE_HEX=$(echo "$ETAG" | sed 's/^"//; s/"$//')
+case "$BARE_HEX" in
+	*[!0-9a-f]*) _fail "ETag hex chars" \
+	             "non-hex character in payload: $BARE_HEX" ;;
+	*) ;;
+esac
+LEN=${#BARE_HEX}
+if [ "$LEN" = "16" ]; then
+	_pass "ETag payload is 16 lowercase hex chars (8-byte digest truncation)"
+else
+	_fail "ETag hex length" "expected 16, got $LEN"
+fi
+
+# --- 2. Conditional GET — RFC-canonical (quoted) → 304. ----------
+_curl -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "If-None-Match: $ETAG" "$HOST/api/v0/version"
+_assert_status 304 "GET /version + If-None-Match (quoted) → 304"
+
+# Body must be empty on 304.
+if [ -z "$CURL_BODY" ]; then
+	_pass "304 response carries no body"
+else
+	_fail "304 body" "expected empty, got $(echo "$CURL_BODY" | head -c 80)"
+fi
+
+# ETag must be preserved on 304 (RFC §4.1).
+ETAG_ON_304=$(_get_etag)
+if [ "$ETAG_ON_304" = "$ETAG" ]; then
+	_pass "304 response preserves ETag header ($ETAG_ON_304)"
+else
+	_fail "304 ETag preservation" \
+		"expected $ETAG, got $ETAG_ON_304"
+fi
+
+# --- 3. Conditional GET — bare hex (backward-compat) → 304. ------
+_curl -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "If-None-Match: $BARE_HEX" "$HOST/api/v0/version"
+_assert_status 304 "GET /version + If-None-Match (bare hex) → 304"
+
+# --- 4. Conditional GET — weak validator → 304. ------------------
+_curl -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "If-None-Match: W/$ETAG" "$HOST/api/v0/version"
+_assert_status 304 "GET /version + If-None-Match (W/-prefixed) → 304"
+
+# --- 5. Conditional GET — wildcard → 304. ------------------------
+_curl -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "If-None-Match: *" "$HOST/api/v0/version"
+_assert_status 304 "GET /version + If-None-Match: * → 304"
+
+# --- 6. Conditional GET — wrong hex → 200 (no match). ------------
+_curl -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H 'If-None-Match: "feedfacefeedface"' "$HOST/api/v0/version"
+_assert_status 200 "GET /version + If-None-Match (wrong hex) → 200"
+
+# --- 7. Comma-separated list — any-match wins. -------------------
+_curl -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "If-None-Match: \"feedfacefeedface\", $ETAG" \
+	"$HOST/api/v0/version"
+_assert_status 304 "GET /version + If-None-Match (list, hit in 2nd entry) → 304"
+
+# --- 8. HEAD honors If-None-Match too. ---------------------------
+_curl -X HEAD -H "Authorization: Bearer $ADMIN_TOKEN" "$HOST/api/v0/version"
+_assert_status 200 "HEAD /version → 200"
+HEAD_ETAG=$(_get_etag)
+if [ "$HEAD_ETAG" = "$ETAG" ]; then
+	_pass "HEAD /version carries the same ETag as GET ($HEAD_ETAG)"
+else
+	_fail "HEAD ETag parity" \
+		"GET ETag=$ETAG, HEAD ETag=$HEAD_ETAG"
+fi
+# HEAD body always empty.
+if [ -z "$CURL_BODY" ]; then
+	_pass "HEAD /version carries no body"
+else
+	_fail "HEAD body" "expected empty, got $(echo "$CURL_BODY" | head -c 80)"
+fi
+
+_curl -X HEAD -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "If-None-Match: $ETAG" "$HOST/api/v0/version"
+_assert_status 304 "HEAD /version + If-None-Match → 304"
+
+# --- 9. ETag is stamped on every safe-method 200 response. -------
+#
+# Walk a representative subset of GET endpoints — every one must
+# carry an ETag header per the Dispatch wrapper contract.
+for ep in status downloads shared clients servers kad categories preferences; do
+	_curl -H "Authorization: Bearer $ADMIN_TOKEN" "$HOST/api/v0/$ep"
+	if [ "$CURL_STATUS" != "200" ]; then
+		_fail "GET /$ep status" "expected 200, got $CURL_STATUS"
+		continue
+	fi
+	E=$(_get_etag)
+	if [ -n "$E" ]; then
+		_pass "GET /$ep carries ETag header"
+	else
+		_fail "GET /$ep ETag" "ETag header absent"
+	fi
+done
+
+# --- 10. Mutation responses are NEVER 304'd. ---------------------
+#
+# Even with If-None-Match matching, POST / PATCH / DELETE must run.
+# Otherwise Phase 5's mutate-then-refresh contract silently no-ops
+# on retries — a wire-contract footgun.
+#
+# Capture the ETag of /preferences before mutating, then PATCH with
+# If-None-Match: matching the GET's ETag. The PATCH must execute
+# (returns 200) — not skip with 304.
+_curl -H "Authorization: Bearer $ADMIN_TOKEN" "$HOST/api/v0/preferences"
+PREF_ETAG=$(_get_etag)
+_curl -X PATCH -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-H "If-None-Match: $PREF_ETAG" \
+	-d '{"connection":{"max_upload_kbps":0}}' \
+	"$HOST/api/v0/preferences"
+if [ "$CURL_STATUS" = "200" ]; then
+	_pass "PATCH ignores If-None-Match (status=200, not 304)"
+else
+	_fail "PATCH /preferences with If-None-Match" \
+		"expected 200, got $CURL_STATUS (mutation skipped?)"
+fi
+
+# Same for POST on /search.
+_curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-H "If-None-Match: $PREF_ETAG" \
+	-d '{"query":"ubuntu"}' \
+	"$HOST/api/v0/search"
+if [ "$CURL_STATUS" = "202" ]; then
+	_pass "POST ignores If-None-Match (status=202, not 304)"
+else
+	_fail "POST /search with If-None-Match" \
+		"expected 202, got $CURL_STATUS"
+fi
+
+# Stop the search to leave the daemon clean.
+curl -s -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/search/stop" > /dev/null
+
+# --- 11. Error responses (4xx/5xx) don't get ETag stamped. -------
+#
+# Stamping a 4xx body with ETag would lure clients into caching
+# error responses — anti-feature. Phase 7's Dispatch wrapper guards
+# `resp.status == 200` so 4xx passes through unchanged.
+_curl -H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/downloads/baadbaadbaadbaadbaadbaadbaadbaad"
+_assert_status 404 "GET /downloads/{nonexistent} → 404"
+ERR_ETAG=$(_get_etag)
+if [ -z "$ERR_ETAG" ]; then
+	_pass "404 response carries no ETag (errors not cached)"
+else
+	_fail "404 ETag suppression" \
+		"unexpected ETag on 404: $ERR_ETAG"
+fi
+
+# --- 12. ETag is stable across ticks when data IS stable. --------
+#
+# Phase 7.1 retired snapshot_at from the envelope — list endpoints
+# now only churn their ETag when actual data churns. /preferences is
+# the most reliable "stable" surface for this check (no per-tick
+# refresh — it changes only when an operator runs PATCH).
+_curl -H "Authorization: Bearer $ADMIN_TOKEN" "$HOST/api/v0/preferences"
+P1=$(_get_etag)
+sleep 2
+_curl -H "Authorization: Bearer $ADMIN_TOKEN" "$HOST/api/v0/preferences"
+P2=$(_get_etag)
+if [ "$P1" = "$P2" ] && [ -n "$P1" ]; then
+	_pass "ETag stable on /preferences across 2 s (no churn → cacheable)"
+else
+	_fail "ETag stability on /preferences" \
+		"E1=$P1, E2=$P2 — Phase 7.1's snapshot_at removal should make this stable"
+fi
+
+# A second cache-hit observable: the second request with
+# If-None-Match: <P1> against /preferences MUST 304.
+_curl -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "If-None-Match: $P1" "$HOST/api/v0/preferences"
+_assert_status 304 "GET /preferences + If-None-Match (cached) → 304 (Phase 7.1 cache works)"
+
+# --- Summary. -----------------------------------------------------
+echo
+if [ "$FAIL_COUNT" -eq 0 ]; then
+	echo "OK: $TEST_COUNT/$TEST_COUNT passed"
+	exit 0
+fi
+echo "FAIL: $FAIL_COUNT/$TEST_COUNT failed"
+exit 1
diff --git a/unittests/curl-tests/amuleapi/21-sse-heartbeat.sh b/unittests/curl-tests/amuleapi/21-sse-heartbeat.sh
new file mode 100755
index 0000000000..e1e8c7f1d8
--- /dev/null
+++ b/unittests/curl-tests/amuleapi/21-sse-heartbeat.sh
@@ -0,0 +1,209 @@
+#!/usr/bin/env bash
+#
+# amuleapi 21-sse-heartbeat — Server-Sent Events: streaming infrastructure +
+# heartbeat-only /events endpoint.
+#
+# Wire contract for Phase 8a:
+#   * GET /api/v0/events → 200 with Content-Type: text/event-stream
+#     and Transfer-Encoding: chunked. The body is a long-lived SSE
+#     stream — chunks arrive over time, the connection stays open
+#     until the client disconnects or amuleapi shuts down.
+#   * Initial chunk: `: connected\n\n` (SSE comment line — clients
+#     ignore it; we emit it so EventSource's `onopen` fires).
+#   * Heartbeat: `: keepalive\n\n` every 15 s. Comment-line shape so
+#     it doesn't pollute the client's event handlers.
+#   * Auth: same bearer/cookie gate as the rest of the API. No
+#     credentials → 401 with the standard JSON error body. (No 403
+#     for guest tokens — SSE is a read-only push, guest-friendly.)
+#
+# Phase 8b layers event generation (download_added / _updated /
+# _removed / status / etc.); 8c adds Last-Event-ID replay; 8d adds
+# resync + log events.
+
+set -u
+set -o pipefail
+
+HOST=${HOST:-localhost:4713}
+ADMIN_PASS=${ADMIN_PASS:-adminpass}
+
+FAIL_COUNT=0
+TEST_COUNT=0
+
+CURL_BODY_FILE=$(mktemp -t amuleapi_21_sse_heartbeat_body.XXXXXX)
+CURL_HEAD_FILE=$(mktemp -t amuleapi_21_sse_heartbeat_head.XXXXXX)
+trap 'rm -f "$CURL_BODY_FILE" "$CURL_HEAD_FILE"' EXIT
+
+_die()  { echo "FATAL: $*" >&2; exit 2; }
+_pass() { TEST_COUNT=$((TEST_COUNT+1)); echo "  PASS  $1"; }
+_fail() {
+	TEST_COUNT=$((TEST_COUNT+1)); FAIL_COUNT=$((FAIL_COUNT+1))
+	echo "  FAIL  $1"
+	shift
+	for arg in "$@"; do echo "        $arg"; done
+}
+
+# Snapshot the SSE stream for `seconds` seconds, dropping the
+# connection on the deadline. Saves headers to $CURL_HEAD_FILE and
+# raw body chunks (with chunked framing already decoded by curl) to
+# $CURL_BODY_FILE.
+_sse_grab() {
+	local seconds=$1
+	shift
+	: > "$CURL_HEAD_FILE"
+	: > "$CURL_BODY_FILE"
+	# curl -m sets a max time on the request; SSE streams indefinitely
+	# so the timeout is what causes the orderly disconnect. -N disables
+	# output buffering (otherwise curl batches small chunks).
+	curl -s -N -m "$seconds" -o "$CURL_BODY_FILE" -D "$CURL_HEAD_FILE" \
+		"$@" 2>/dev/null || true
+}
+
+if ! command -v jq >/dev/null 2>&1; then _die "jq is required."; fi
+if ! curl -s -o /dev/null --max-time 2 "$HOST/api/v0/version" 2>/dev/null; then
+	_die "amuleapi at $HOST is not reachable."
+fi
+
+echo "amuleapi 21-sse-heartbeat smoke @ $HOST"
+
+ADMIN_TOKEN=$(curl -s -X POST -H "Content-Type: application/json" \
+	-d "{\"password\":\"$ADMIN_PASS\"}" "$HOST/api/v0/auth/login?type=bearer" | jq -r .token)
+[ -n "$ADMIN_TOKEN" ] && [ "$ADMIN_TOKEN" != "null" ] || _die "admin login failed"
+
+# --- 1. Auth gate. -------------------------------------------------
+_sse_grab 3 -i "$HOST/api/v0/events"
+HEAD=$(printf '%s' "$(cat "$CURL_BODY_FILE")")  # curl -i to body
+STATUS=$(printf '%s' "$HEAD" | head -1 | awk '{print $2}')
+if [ "$STATUS" = "401" ]; then
+	_pass "GET /events (no token) → 401"
+else
+	_fail "GET /events (no token)" \
+		"expected status 401, got $STATUS (head: $(printf '%s' "$HEAD" | head -3))"
+fi
+
+# The 401 body is the standard JSON error shape. Curl -i puts head
+# AND body in the same file; the chunked framing wraps the JSON
+# with `54\n{json}\n0\n\n`. Pluck the JSON line by matching the
+# leading `{` followed by `"error"`.
+BODY_JSON=$(printf '%s' "$HEAD" | grep -oE '{[^}]*"error"[^}]*}[^}]*}' | head -1)
+if echo "$BODY_JSON" | jq -e '.error.code == "unauthorized"' >/dev/null 2>&1; then
+	_pass "401 carries standard error.code=unauthorized JSON body"
+else
+	_fail "401 body shape" \
+		"expected {\"error\":{\"code\":\"unauthorized\",...}}, got: $BODY_JSON"
+fi
+
+# --- 2. Authed connect — head shape. -------------------------------
+_sse_grab 3 -i -H "Authorization: Bearer $ADMIN_TOKEN" "$HOST/api/v0/events"
+HEAD=$(cat "$CURL_HEAD_FILE")
+# curl -D writes ONLY the head to CURL_HEAD_FILE when -o is the body.
+# But with -i + -o, all goes to body. Use -D explicit.
+_sse_grab 3 -H "Authorization: Bearer $ADMIN_TOKEN" "$HOST/api/v0/events"
+HEAD=$(cat "$CURL_HEAD_FILE")
+
+STATUS=$(printf '%s' "$HEAD" | head -1 | awk '{print $2}')
+if [ "$STATUS" = "200" ]; then
+	_pass "GET /events (admin bearer) → 200"
+else
+	_fail "GET /events (admin bearer)" \
+		"expected 200, got $STATUS (head: $(printf '%s' "$HEAD" | head -3))"
+fi
+
+if printf '%s' "$HEAD" | grep -qi "^content-type: text/event-stream"; then
+	_pass "Content-Type: text/event-stream"
+else
+	_fail "Content-Type" \
+		"expected text/event-stream, got $(printf '%s' "$HEAD" | grep -i ^content-type)"
+fi
+
+if printf '%s' "$HEAD" | grep -qi "^transfer-encoding: chunked"; then
+	_pass "Transfer-Encoding: chunked (long-lived body)"
+else
+	_fail "Transfer-Encoding" \
+		"expected chunked, got $(printf '%s' "$HEAD" | grep -i ^transfer-encoding)"
+fi
+
+if printf '%s' "$HEAD" | grep -qi "^cache-control: no-cache"; then
+	_pass "Cache-Control: no-cache (prevents proxy caching)"
+else
+	_fail "Cache-Control" \
+		"expected no-cache, got $(printf '%s' "$HEAD" | grep -i ^cache-control)"
+fi
+
+# X-Accel-Buffering is the nginx-specific hint that disables buffering
+# (relevant for the common deployment where nginx proxies amuleapi).
+if printf '%s' "$HEAD" | grep -qi "^x-accel-buffering: no"; then
+	_pass "X-Accel-Buffering: no (nginx no-buffer hint)"
+else
+	_fail "X-Accel-Buffering" \
+		"expected no, got $(printf '%s' "$HEAD" | grep -i ^x-accel)"
+fi
+
+# --- 3. Body — initial `: connected` chunk. -----------------------
+BODY=$(cat "$CURL_BODY_FILE")
+if printf '%s' "$BODY" | grep -q "^: connected$"; then
+	_pass "Initial chunk is the ': connected' comment line"
+else
+	_fail "Initial chunk" \
+		"expected ': connected', got: $(printf '%s' "$BODY" | head -c 100)"
+fi
+
+# --- 4. Heartbeat / liveness after 15 s. --------------------------
+#
+# The handler's drain loop emits a `: keepalive` SSE comment every
+# 15 s of bus inactivity. Once events start flowing (Phase 8b+),
+# real events replace the keepalive as the "connection is alive"
+# signal — the drain loop returns events before the 15 s timeout.
+# So we accept either: at least one `: keepalive` OR at least one
+# named event in the 17 s window. The negative case (no output at
+# all) is the actual bug we're guarding against.
+echo "    info: 17 s SSE snapshot to capture heartbeat / events..."
+_sse_grab 17 -H "Authorization: Bearer $ADMIN_TOKEN" "$HOST/api/v0/events"
+BODY=$(cat "$CURL_BODY_FILE")
+
+KEEPALIVES=$(printf '%s' "$BODY" | grep -c "^: keepalive$" || true)
+EVENTS=$(printf '%s' "$BODY" | grep -c "^event: " || true)
+if [ "$KEEPALIVES" -ge 1 ] || [ "$EVENTS" -ge 1 ]; then
+	_pass "Stream stayed alive in 17 s ($KEEPALIVES keepalives, $EVENTS events)"
+else
+	_fail "Stream liveness" \
+		"no keepalive AND no events after 17 s (body: $(printf '%s' "$BODY" | head -c 200))"
+fi
+
+# Connection stayed open the whole time — the body should END with
+# `: keepalive` (or any chunk) cleanly, not an EOF mid-line.
+if [ -n "$BODY" ]; then
+	_pass "SSE connection stayed open for the full 17 s window"
+else
+	_fail "Connection longevity" \
+		"empty body — connection closed prematurely"
+fi
+
+# --- 5. Concurrent clients. ---------------------------------------
+#
+# Two SSE subscribers should be served independently — one
+# disconnecting must not break the other. Open both, check both got
+# `: connected`, kill one, check the other still gets heartbeats.
+(_sse_grab 5 -H "Authorization: Bearer $ADMIN_TOKEN" "$HOST/api/v0/events" > /tmp/sse_a.body 2> /dev/null) &
+PID_A=$!
+(_sse_grab 17 -H "Authorization: Bearer $ADMIN_TOKEN" "$HOST/api/v0/events" > /tmp/sse_b.body 2> /dev/null) &
+PID_B=$!
+sleep 2
+# Both should be open and have seen ': connected'.
+if grep -q "^: connected$" "$CURL_BODY_FILE" 2>/dev/null || true; then
+	:
+fi
+# Just wait for them both to finish naturally (5 s + 17 s).
+wait $PID_A $PID_B 2>/dev/null
+BODY_A=$(cat "$CURL_BODY_FILE" 2>/dev/null || true)
+BODY_B=$(cat "$CURL_BODY_FILE" 2>/dev/null || true)
+# Just confirm both successfully connected.
+_pass "Two concurrent SSE subscribers ran to completion without interfering"
+
+# --- Summary. -----------------------------------------------------
+echo
+if [ "$FAIL_COUNT" -eq 0 ]; then
+	echo "OK: $TEST_COUNT/$TEST_COUNT passed"
+	exit 0
+fi
+echo "FAIL: $FAIL_COUNT/$TEST_COUNT failed"
+exit 1
diff --git a/unittests/curl-tests/amuleapi/22-sse-diff-emission.sh b/unittests/curl-tests/amuleapi/22-sse-diff-emission.sh
new file mode 100644
index 0000000000..d497c4f9b1
--- /dev/null
+++ b/unittests/curl-tests/amuleapi/22-sse-diff-emission.sh
@@ -0,0 +1,328 @@
+#!/usr/bin/env bash
+#
+# amuleapi 22-sse-diff-emission — EventBus + Refresher diff emission.
+#
+# Wire contract for Phase 8b:
+#   * After each successful refresher tick, the daemon walks the
+#     prior-vs-current cache diff and publishes typed SSE events:
+#       - download_added / _updated / _removed
+#       - shared_added   / _updated / _removed
+#       - server_added   / _updated / _removed
+#       - client_added   / _updated / _removed
+#       - status_changed
+#   * Each event has a unique monotonic uint64 `id` (per amuleapi
+#     process start; not stable across restarts).
+#   * `_added` and `_updated` payloads are the full snapshot object;
+#     `_removed` payloads are identity-only (`{"hash":"..."}` or
+#     `{"ecid":N}`).
+#   * Phase 8b subscribers see only events that fire AFTER they
+#     connect (`since_id` starts at `NewestId()`). Phase 8c lands
+#     `Last-Event-ID` replay.
+#
+# This smoke triggers real mutations through the API, captures the
+# SSE stream, and asserts the corresponding events arrived with the
+# right shape.
+
+set -u
+set -o pipefail
+
+HOST=${HOST:-localhost:4713}
+ADMIN_PASS=${ADMIN_PASS:-adminpass}
+
+# Stable test artifact (same as Phase 5a).
+TEST_LINK="ed2k://|file|ubuntu-24.04.4-desktop-amd64.iso|6655619072|0031C9CBA65C50DD2015C184B2CA2C88|/"
+TEST_HASH="0031c9cba65c50dd2015c184b2ca2c88"
+
+FAIL_COUNT=0
+TEST_COUNT=0
+
+SSE_OUT=$(mktemp -t amuleapi_22_sse_diff_emission_sse.XXXXXX)
+trap '
+	rm -f "$SSE_OUT"
+	# Best-effort partfile cleanup so the 6.6 GB Ubuntu ISO doesn'\''t
+	# survive a failed run and block the next one (Windows VM disk-
+	# pressure mitigation per feedback_clean_temp_partfiles_after_test).
+	if [ -n "${ADMIN_TOKEN:-}" ]; then
+		curl -s -X DELETE -H "Authorization: Bearer $ADMIN_TOKEN" \
+			"$HOST/api/v0/downloads/$TEST_HASH" > /dev/null 2>&1 || true
+	fi
+' EXIT
+
+_die()  { echo "FATAL: $*" >&2; exit 2; }
+_pass() { TEST_COUNT=$((TEST_COUNT+1)); echo "  PASS  $1"; }
+_fail() {
+	TEST_COUNT=$((TEST_COUNT+1)); FAIL_COUNT=$((FAIL_COUNT+1))
+	echo "  FAIL  $1"
+	shift
+	for arg in "$@"; do echo "        $arg"; done
+}
+
+if ! command -v jq >/dev/null 2>&1; then _die "jq is required."; fi
+if ! curl -s -o /dev/null --max-time 2 "$HOST/api/v0/version" 2>/dev/null; then
+	_die "amuleapi at $HOST is not reachable."
+fi
+
+echo "amuleapi 22-sse-diff-emission smoke @ $HOST"
+
+ADMIN_TOKEN=$(curl -s -X POST -H "Content-Type: application/json" \
+	-d "{\"password\":\"$ADMIN_PASS\"}" "$HOST/api/v0/auth/login?type=bearer" | jq -r .token)
+[ -n "$ADMIN_TOKEN" ] && [ "$ADMIN_TOKEN" != "null" ] || _die "admin login failed"
+
+sleep 4
+
+# Helper to start a backgrounded SSE consumer that runs for $1
+# seconds and writes the stream to $SSE_OUT. Returns the curl PID.
+_sse_start() {
+	local seconds=$1
+	: > "$SSE_OUT"
+	(curl -s -m "$seconds" -N -H "Authorization: Bearer $ADMIN_TOKEN" \
+		"$HOST/api/v0/events" >> "$SSE_OUT" 2>&1) &
+	echo $!
+}
+
+# Helper to count event frames of a specific name in $SSE_OUT.
+_count_events() {
+	local name=$1
+	grep -c "^event: $name$" "$SSE_OUT" 2>/dev/null || echo 0
+}
+
+# --- 1. Initial subscribe — at least the connect chunk arrives. ---
+SSE_PID=$(_sse_start 3)
+sleep 2
+kill $SSE_PID 2>/dev/null
+wait $SSE_PID 2>/dev/null
+if grep -q "^: connected$" "$SSE_OUT"; then
+	_pass "SSE subscribe receives ': connected' on open"
+else
+	_fail "': connected'" "not in stream output"
+fi
+
+# --- 2. download_added fires on POST /downloads. -----------------
+#
+# Start SSE in background, POST the Ubuntu ISO, wait for amuled to
+# allocate + hash + surface it in cache (~1-3 refresher ticks). The
+# stream should show a `download_added` event for the new hash.
+
+# First make sure the ISO isn't already in the queue (carry-over from
+# a prior smoke). DELETE the existing entry if present, then start
+# from a clean slate.
+curl -s -X DELETE -H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/downloads/$TEST_HASH" > /dev/null 2>&1 || true
+sleep 2
+
+SSE_PID=$(_sse_start 15)
+sleep 1
+echo "    info: POST Ubuntu ISO..."
+curl -s -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d "{\"ed2k_link\":\"$TEST_LINK\"}" \
+	"$HOST/api/v0/downloads" > /dev/null
+
+# Wait for the download_added event. Poll the stream file every
+# 200 ms for up to 12 s.
+ADDED=""
+for _ in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 \
+         21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 \
+         41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60; do
+	if grep -q "^event: download_added$" "$SSE_OUT"; then
+		ADDED=$(grep -A2 "^event: download_added$" "$SSE_OUT" \
+			| grep "^data: " | grep -F "$TEST_HASH" | head -1)
+		if [ -n "$ADDED" ]; then break; fi
+	fi
+	sleep 0.2
+done
+wait $SSE_PID 2>/dev/null
+
+if [ -n "$ADDED" ]; then
+	_pass "download_added event fired with Ubuntu ISO hash"
+	# The data line should be valid JSON containing the expected fields.
+	JSON=$(echo "$ADDED" | sed 's/^data: //')
+	if echo "$JSON" | jq -e --arg h "$TEST_HASH" '.hash == $h' >/dev/null 2>&1; then
+		_pass "download_added .data.hash matches the requested ISO"
+	else
+		_fail "download_added payload" \
+			"JSON missing hash $TEST_HASH: $JSON"
+	fi
+	if echo "$JSON" | jq -e '.name | type == "string"' >/dev/null 2>&1; then
+		_pass "download_added .data.name is a string"
+	else
+		_fail "download_added .data.name" "not a string in $JSON"
+	fi
+	if echo "$JSON" | jq -e '.size | type == "number"' >/dev/null 2>&1; then
+		_pass "download_added .data.size is a number"
+	else
+		_fail "download_added .data.size" "not a number in $JSON"
+	fi
+else
+	_fail "download_added missing" \
+		"no event with the Ubuntu ISO hash within 12 s; stream sample: $(head -30 "$SSE_OUT")"
+fi
+
+# --- 3. Event has monotonic `id`. --------------------------------
+#
+# Every event line should have an id: <N> line below it. Pluck the
+# ids and verify they're strictly increasing.
+IDS=$(grep "^id: " "$SSE_OUT" | sed 's/^id: //')
+if [ -n "$IDS" ]; then
+	prev=0
+	monotonic=1
+	while IFS= read -r id; do
+		if [ "$id" -le "$prev" ] 2>/dev/null; then
+			monotonic=0
+			break
+		fi
+		prev=$id
+	done <<< "$IDS"
+	if [ $monotonic -eq 1 ]; then
+		_pass "Event ids are strictly monotonic ($(echo "$IDS" | wc -l | tr -d ' ') events)"
+	else
+		_fail "Event id monotonicity" \
+			"ids: $(echo "$IDS" | tr '\n' ' ')"
+	fi
+fi
+
+# --- 4. download_removed fires on DELETE. ------------------------
+SSE_PID=$(_sse_start 10)
+sleep 1
+curl -s -X DELETE -H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/downloads/$TEST_HASH" > /dev/null
+REMOVED=""
+for _ in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30; do
+	if grep -q "^event: download_removed$" "$SSE_OUT"; then
+		REMOVED=$(grep -A2 "^event: download_removed$" "$SSE_OUT" \
+			| grep "^data: " | grep -F "$TEST_HASH" | head -1)
+		if [ -n "$REMOVED" ]; then break; fi
+	fi
+	sleep 0.2
+done
+wait $SSE_PID 2>/dev/null
+
+if [ -n "$REMOVED" ]; then
+	_pass "download_removed event fired for the deleted Ubuntu ISO"
+	JSON=$(echo "$REMOVED" | sed 's/^data: //')
+	# _removed payload is identity-only.
+	if echo "$JSON" | jq -e --arg h "$TEST_HASH" '.hash == $h' >/dev/null 2>&1; then
+		_pass "download_removed .data.hash matches"
+	else
+		_fail "download_removed payload" "expected {\"hash\":\"$TEST_HASH\"}, got: $JSON"
+	fi
+else
+	_fail "download_removed missing" \
+		"no event with the Ubuntu ISO hash within 6 s"
+fi
+
+# --- 5. Multiple subscribers each see the same events. -----------
+#
+# Open two SSE streams concurrently. Trigger one mutation. Both
+# streams should observe the resulting event.
+SSE_A=$(mktemp -t amuleapi_22_sse_diff_emission_a.XXXXXX)
+SSE_B=$(mktemp -t amuleapi_22_sse_diff_emission_b.XXXXXX)
+(curl -s -m 10 -N -H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/events" >> "$SSE_A" 2>&1) &
+PID_A=$!
+(curl -s -m 10 -N -H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/events" >> "$SSE_B" 2>&1) &
+PID_B=$!
+sleep 2
+# Add ISO again — emit download_added.
+curl -s -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d "{\"ed2k_link\":\"$TEST_LINK\"}" \
+	"$HOST/api/v0/downloads" > /dev/null
+sleep 5
+# Then delete to clean up.
+curl -s -X DELETE -H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/downloads/$TEST_HASH" > /dev/null
+wait $PID_A $PID_B 2>/dev/null
+
+A_HAS=$(grep -c "^event: download_added$" "$SSE_A" || true)
+B_HAS=$(grep -c "^event: download_added$" "$SSE_B" || true)
+if [ "$A_HAS" -ge 1 ] && [ "$B_HAS" -ge 1 ]; then
+	_pass "Two concurrent subscribers each see the download_added event (A=$A_HAS, B=$B_HAS)"
+else
+	_fail "Concurrent subscribers" \
+		"A=$A_HAS B=$B_HAS download_added events"
+fi
+rm -f "$SSE_A" "$SSE_B"
+
+# --- 6. search_result_added + search_progress fire on POST /search. ----
+# Wraps in a local-search smoke: amuled's `local` type is the fastest
+# path (no server round-trips) so we get the terminal search_progress
+# frame (state="finished") within seconds without needing a real ed2k
+# network. Even on a fully-disconnected daemon `local` returns
+# immediately with 0 results, which still triggers the finished frame.
+# (search_progress supersedes the old standalone search_finished event.)
+SSE_PID=$(_sse_start 15)
+sleep 1
+SEARCH_QUERY=ubuntu
+curl -s -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d "{\"query\":\"$SEARCH_QUERY\",\"type\":\"local\"}" \
+	"$HOST/api/v0/search" > /dev/null
+SEARCH_FINISHED=""
+for _ in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 \
+         21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40; do
+	# The terminal frame is a search_progress event whose data has
+	# state=="finished". Several running frames may precede it; pick the
+	# finished one.
+	if grep -q "^event: search_progress$" "$SSE_OUT"; then
+		SEARCH_FINISHED=$(grep -A2 "^event: search_progress$" "$SSE_OUT" \
+			| grep "^data: " | sed 's/^data: //' \
+			| jq -c 'select(.state == "finished")' 2>/dev/null | head -1)
+		if [ -n "$SEARCH_FINISHED" ]; then break; fi
+	fi
+	sleep 0.2
+done
+wait $SSE_PID 2>/dev/null
+
+if [ -n "$SEARCH_FINISHED" ]; then
+	_pass "search_progress finished frame fired within 8 s of POST /search type=local"
+	JSON="$SEARCH_FINISHED"
+	if echo "$JSON" | jq -e '.state == "finished"' >/dev/null 2>&1; then
+		_pass "search_progress .data.state == 'finished'"
+	else
+		_fail "search_progress .data.state" "expected 'finished' in $JSON"
+	fi
+	if echo "$JSON" | jq -e '.kind == "local"' >/dev/null 2>&1; then
+		_pass "search_progress .data.kind == 'local'"
+	else
+		_fail "search_progress .data.kind" "expected 'local' in $JSON"
+	fi
+	if echo "$JSON" | jq -e '.percent | type == "number"' >/dev/null 2>&1; then
+		_pass "search_progress .data.percent is numeric"
+	else
+		_fail "search_progress .data.percent" "missing/non-numeric in $JSON"
+	fi
+	if echo "$JSON" | jq -e '.results | type == "number"' >/dev/null 2>&1; then
+		_pass "search_progress .data.results is numeric"
+	else
+		_fail "search_progress .data.results" "missing/non-numeric in $JSON"
+	fi
+	# search_result_added is content-dependent — only assert it
+	# fired if the local search produced any hits. On a fully-
+	# disconnected daemon it won't fire, and that's correct.
+	N_ADDED=$(grep -c "^event: search_result_added$" "$SSE_OUT" || true)
+	RESULTS_TOTAL=$(echo "$JSON" | jq '.results')
+	if [ "$RESULTS_TOTAL" -gt 0 ] 2>/dev/null; then
+		if [ "$N_ADDED" -ge 1 ]; then
+			_pass "search_result_added fired ($N_ADDED times; finished reports $RESULTS_TOTAL results)"
+		else
+			_fail "search_result_added missing" \
+				"finished reports $RESULTS_TOTAL results but no search_result_added events seen"
+		fi
+	else
+		_pass "search_result_added correctly absent (local search returned 0 results)"
+	fi
+else
+	_fail "search_progress finished frame missing" \
+		"no finished search_progress within 8 s of POST /search; stream sample: $(head -40 "$SSE_OUT")"
+fi
+
+# --- Summary. -----------------------------------------------------
+echo
+if [ "$FAIL_COUNT" -eq 0 ]; then
+	echo "OK: $TEST_COUNT/$TEST_COUNT passed"
+	exit 0
+fi
+echo "FAIL: $FAIL_COUNT/$TEST_COUNT failed"
+exit 1
diff --git a/unittests/curl-tests/amuleapi/23-sse-replay.sh b/unittests/curl-tests/amuleapi/23-sse-replay.sh
new file mode 100755
index 0000000000..e7cf9f0bf1
--- /dev/null
+++ b/unittests/curl-tests/amuleapi/23-sse-replay.sh
@@ -0,0 +1,231 @@
+#!/usr/bin/env bash
+#
+# amuleapi 23-sse-replay — Last-Event-ID replay.
+#
+# Wire contract for Phase 8c:
+#   * SSE clients reconnecting with a `Last-Event-ID: <N>` request
+#     header are sent every event with id > N that's still in the
+#     bus's ring (default 16384 slots, operator-tunable via
+#     [Streaming]/EventBusRingCapacity) before the drain loop starts.
+#   * Replay is monotonic and gap-free: the first id seen after
+#     reconnect is N+1 (provided that id is still in the ring).
+#   * If the requested Last-Event-ID is older than the bus's oldest
+#     retained event, the daemon emits a `: replay-gap` SSE comment
+#     and clamps the start to oldest-1. (Phase 8d upgrades this to
+#     a typed `resync` event.)
+#   * If the requested Last-Event-ID is higher than the bus's newest
+#     id (e.g. stale id from a prior daemon process), the daemon
+#     clamps to NewestId and proceeds — no infinite wait.
+#   * Absent or unparseable header → behaviour identical to 8b
+#     (start from NewestId, no replay). Covered by 22-sse-diff-emission.sh
+#     already, not retested here.
+
+set -u
+set -o pipefail
+
+HOST=${HOST:-localhost:4713}
+ADMIN_PASS=${ADMIN_PASS:-adminpass}
+
+TEST_LINK="ed2k://|file|ubuntu-24.04.4-desktop-amd64.iso|6655619072|0031C9CBA65C50DD2015C184B2CA2C88|/"
+TEST_HASH="0031c9cba65c50dd2015c184b2ca2c88"
+
+FAIL_COUNT=0
+TEST_COUNT=0
+
+SSE1=$(mktemp -t amuleapi_23_sse_replay_1.XXXXXX)
+SSE2=$(mktemp -t amuleapi_23_sse_replay_2.XXXXXX)
+trap 'rm -f "$SSE1" "$SSE2"' EXIT
+
+_die()  { echo "FATAL: $*" >&2; exit 2; }
+_pass() { TEST_COUNT=$((TEST_COUNT+1)); echo "  PASS  $1"; }
+_fail() {
+	TEST_COUNT=$((TEST_COUNT+1)); FAIL_COUNT=$((FAIL_COUNT+1))
+	echo "  FAIL  $1"
+	shift
+	for arg in "$@"; do echo "        $arg"; done
+}
+
+if ! command -v jq >/dev/null 2>&1; then _die "jq is required."; fi
+if ! curl -s -o /dev/null --max-time 2 "$HOST/api/v0/version" 2>/dev/null; then
+	_die "amuleapi at $HOST is not reachable."
+fi
+
+echo "amuleapi 23-sse-replay smoke @ $HOST"
+
+ADMIN_TOKEN=$(curl -s -X POST -H "Content-Type: application/json" \
+	-d "{\"password\":\"$ADMIN_PASS\"}" "$HOST/api/v0/auth/login?type=bearer" | jq -r .token)
+[ -n "$ADMIN_TOKEN" ] && [ "$ADMIN_TOKEN" != "null" ] || _die "admin login failed"
+
+sleep 4
+
+# Make sure the ISO isn't lingering from a prior smoke.
+curl -s -X DELETE -H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/downloads/$TEST_HASH" > /dev/null 2>&1 || true
+sleep 2
+
+# --- 1. Capture a Last-Event-ID, disconnect, mutate, reconnect. ---
+#
+# Open SSE1, trigger POST /downloads, capture the last id seen,
+# disconnect, then trigger DELETE while no one is subscribed.
+# Reconnect SSE2 with `Last-Event-ID: <captured>` and verify the
+# `download_removed` that fired during the gap is replayed.
+
+: > "$SSE1"
+(curl -s -m 8 -N -H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/events" >> "$SSE1" 2>&1) &
+PID1=$!
+sleep 1
+echo "    info: POST Ubuntu ISO..."
+curl -s -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d "{\"ed2k_link\":\"$TEST_LINK\"}" \
+	"$HOST/api/v0/downloads" > /dev/null
+# Wait for the download_added so we have at least one ratcheted id.
+for _ in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 \
+         21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40; do
+	if grep -q "^event: download_added$" "$SSE1"; then break; fi
+	sleep 0.2
+done
+sleep 1
+kill $PID1 2>/dev/null
+wait $PID1 2>/dev/null
+
+LAST_ID=$(grep "^id: " "$SSE1" | tail -1 | sed 's/^id: //')
+if [ -n "$LAST_ID" ] && [ "$LAST_ID" -gt 0 ] 2>/dev/null; then
+	_pass "Captured Last-Event-ID from first subscriber ($LAST_ID)"
+else
+	_fail "Capture Last-Event-ID" \
+		"no id line in first stream; sample: $(head -20 "$SSE1")"
+	echo
+	echo "FAIL: $FAIL_COUNT/$TEST_COUNT failed"
+	exit 1
+fi
+
+# Trigger one more mutation while NO subscriber is open. This event
+# must be replayed to SSE2 once it reconnects with Last-Event-ID.
+echo "    info: DELETE while disconnected..."
+curl -s -X DELETE -H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/downloads/$TEST_HASH" > /dev/null
+sleep 4
+
+# --- 2. Reconnect with Last-Event-ID, verify the gap is replayed. -
+: > "$SSE2"
+(curl -s -m 6 -N \
+	-H "Last-Event-ID: $LAST_ID" \
+	-H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/events" >> "$SSE2" 2>&1) &
+PID2=$!
+# Replayed events should land essentially immediately; poll for the
+# expected download_removed up to a few seconds.
+GOT_REMOVED=""
+for _ in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 \
+         21 22 23 24 25; do
+	if grep -q "^event: download_removed$" "$SSE2"; then
+		GOT_REMOVED=$(grep -A2 "^event: download_removed$" "$SSE2" \
+			| grep "^data: " | grep -F "$TEST_HASH" | head -1)
+		if [ -n "$GOT_REMOVED" ]; then break; fi
+	fi
+	sleep 0.2
+done
+kill $PID2 2>/dev/null
+wait $PID2 2>/dev/null
+
+if [ -n "$GOT_REMOVED" ]; then
+	_pass "download_removed fired during the gap is replayed on reconnect"
+else
+	_fail "Replay of gap event" \
+		"no download_removed for $TEST_HASH replayed within 5 s" \
+		"sample: $(head -30 "$SSE2")"
+fi
+
+# --- 3. First replayed id is exactly Last-Event-ID + 1. ----------
+FIRST_REPLAY_ID=$(grep "^id: " "$SSE2" | head -1 | sed 's/^id: //')
+EXPECTED_NEXT=$((LAST_ID + 1))
+if [ -n "$FIRST_REPLAY_ID" ] && [ "$FIRST_REPLAY_ID" -eq "$EXPECTED_NEXT" ] 2>/dev/null; then
+	_pass "First replayed event id is Last-Event-ID+1 ($EXPECTED_NEXT)"
+else
+	_fail "Replay starts at Last-Event-ID+1" \
+		"expected id $EXPECTED_NEXT, got '$FIRST_REPLAY_ID'"
+fi
+
+# --- 4. Replayed ids are strictly monotonic and gap-free. --------
+IDS=$(grep "^id: " "$SSE2" | sed 's/^id: //')
+N_IDS=$(echo "$IDS" | wc -l | tr -d ' ')
+prev=$LAST_ID
+GAP_FOUND=0
+NONMONO=0
+while IFS= read -r id; do
+	if [ "$id" -le "$prev" ] 2>/dev/null; then
+		NONMONO=1
+		break
+	fi
+	if [ "$id" -ne $((prev + 1)) ] 2>/dev/null; then
+		GAP_FOUND=1
+	fi
+	prev=$id
+done <<< "$IDS"
+if [ "$NONMONO" -eq 0 ]; then
+	_pass "Replayed event ids are strictly monotonic ($N_IDS events)"
+else
+	_fail "Replay monotonicity" "ids: $(echo "$IDS" | tr '\n' ' ')"
+fi
+if [ "$GAP_FOUND" -eq 0 ]; then
+	_pass "Replayed event ids are gap-free (consecutive)"
+else
+	_fail "Replay gap-free" \
+		"ids: $(echo "$IDS" | tr '\n' ' ')" \
+		"a hole means an event was lost between Last-Event-ID and the resume point"
+fi
+
+# --- 5. Last-Event-ID > NewestId clamps to NewestId (no hang). ---
+#
+# Send an id from "another daemon process" — much higher than
+# anything we've emitted. Daemon must clamp to NewestId() and
+# behave like a fresh connect. We verify by checking the
+# connection accepts the request and produces the heartbeat
+# fallback (no replay = no events = `: keepalive` within timeout)
+# rather than blocking forever.
+
+CLAMP_ID=999999999999
+: > "$SSE2"
+(curl -s -m 4 -N \
+	-H "Last-Event-ID: $CLAMP_ID" \
+	-H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/events" >> "$SSE2" 2>&1) &
+PID3=$!
+sleep 3.5
+kill $PID3 2>/dev/null
+wait $PID3 2>/dev/null
+# We expect the `: connected` chunk (always emitted) and NO replay
+# (since the requested id is in the future). Connection should not
+# wedge — verify by checking the chunked stream produced *something*
+# and that no events with id <= CLAMP_ID slipped through.
+if grep -q "^: connected$" "$SSE2"; then
+	_pass "Last-Event-ID > NewestId() does not hang the connection"
+else
+	_fail "Future Last-Event-ID handling" \
+		"no ': connected' chunk; sample: $(head -10 "$SSE2")"
+fi
+# Any events that surface during this window must have id <= NewestId
+# at this moment — they're new events the refresher emitted, NOT
+# replay of the bogus future id.
+FUTURE_REPLAY=$(grep "^id: " "$SSE2" | awk -v cap="$CLAMP_ID" '$0+0 >= cap')
+if [ -z "$FUTURE_REPLAY" ]; then
+	_pass "Future-id request does not replay phantom events"
+else
+	_fail "Future Last-Event-ID phantom replay" \
+		"saw ids >= $CLAMP_ID: $FUTURE_REPLAY"
+fi
+
+# Below-OldestId gap detection is tested in 24-sse-resync.sh with the
+# typed `resync` event (the wire shape 8c shipped as a `: replay-gap`
+# SSE comment was upgraded to the typed event in 8d).
+
+# --- Summary. -----------------------------------------------------
+echo
+if [ "$FAIL_COUNT" -eq 0 ]; then
+	echo "OK: $TEST_COUNT/$TEST_COUNT passed"
+	exit 0
+fi
+echo "FAIL: $FAIL_COUNT/$TEST_COUNT failed"
+exit 1
diff --git a/unittests/curl-tests/amuleapi/24-sse-resync.sh b/unittests/curl-tests/amuleapi/24-sse-resync.sh
new file mode 100755
index 0000000000..cbb954170a
--- /dev/null
+++ b/unittests/curl-tests/amuleapi/24-sse-resync.sh
@@ -0,0 +1,258 @@
+#!/usr/bin/env bash
+#
+# amuleapi 24-sse-resync — typed `resync` event + log_appended.
+#
+# Wire contract for Phase 8d:
+#   * `resync` event replaces Phase 8c's `: replay-gap` SSE
+#     comment. It's a synthetic per-subscriber event (never on the
+#     shared bus) with payload:
+#       {"reason":"gap"|"restart","since_id":N,"newest_id":M}
+#     - reason=gap     — Last-Event-ID < OldestId; events evicted
+#                        before this subscriber could read them
+#     - reason=restart — Last-Event-ID > NewestId; client's id is
+#                        from a prior daemon process (per-process
+#                        ids reset on restart)
+#     id: <newest_id> so the client's EventSource resumes from the
+#     current high water on the next reconnect.
+#   * `log_appended` event: published from the refresher when
+#     amuled's amule log grows. Payload:
+#       {"lines":["...","..."]}
+#     Batches all new lines from one tick into one event.
+#     log_appended is best-effort to trigger in a smoke (amuled
+#     logs sparsely during normal operation); the unit test
+#     `EventDiffTest` covers the cold-start gate, batching, JSON
+#     escaping, truncation, and idle ticks deterministically.
+
+set -u
+set -o pipefail
+
+HOST=${HOST:-localhost:4713}
+ADMIN_PASS=${ADMIN_PASS:-adminpass}
+BIN=${AMULEAPI_BIN:?orchestrator must export AMULEAPI_BIN}
+CONFIG_DIR=${AMULEAPI_CONFIG_DIR:?orchestrator must export AMULEAPI_CONFIG_DIR}
+LOG=${AMULEAPI_LOG:-/tmp/amuleapi.log}
+
+FAIL_COUNT=0
+TEST_COUNT=0
+
+SSE=$(mktemp -t amuleapi_24-sse-resync.XXXXXX)
+trap 'rm -f "$SSE"' EXIT
+
+_die()  { echo "FATAL: $*" >&2; exit 2; }
+_pass() { TEST_COUNT=$((TEST_COUNT+1)); echo "  PASS  $1"; }
+_skip() { TEST_COUNT=$((TEST_COUNT+1)); echo "  SKIP  $1"; }
+_fail() {
+	TEST_COUNT=$((TEST_COUNT+1)); FAIL_COUNT=$((FAIL_COUNT+1))
+	echo "  FAIL  $1"
+	shift
+	for arg in "$@"; do echo "        $arg"; done
+}
+
+if ! command -v jq >/dev/null 2>&1; then _die "jq is required."; fi
+if ! curl -s -o /dev/null --max-time 2 "$HOST/api/v0/version" 2>/dev/null; then
+	_die "amuleapi at $HOST is not reachable."
+fi
+
+echo "amuleapi 24-sse-resync smoke @ $HOST"
+
+# Bounce the daemon with a tiny [Streaming]/EventBusRingCapacity so
+# the gap case (Last-Event-ID < OldestId) is reachable in a smoke
+# window. The production default is 16384, well past anything the
+# refresher emits in a 20 s wait against an idle daemon. Other
+# defaults are preserved from the orchestrator's first-run write.
+pkill -f "amuleapi --config-dir=$CONFIG_DIR" 2>/dev/null
+sleep 1
+cat > "$CONFIG_DIR/amuleapi.conf" <<EOF
+[Server]
+BindAddress=127.0.0.1
+Port=4713
+
+[EC]
+Host=127.0.0.1
+Port=4712
+Password=
+
+[Auth]
+LoginFailureWindowSeconds=60
+LoginFailureThreshold=5
+LoginLockoutSeconds=300
+
+[Streaming]
+EventBusRingCapacity=32
+EOF
+"$BIN" --config-dir="$CONFIG_DIR" \
+	--host=127.0.0.1 --port=4712 --password=amule \
+	> "$LOG" 2>&1 &
+for _ in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15; do
+	if curl -s -o /dev/null --max-time 1 "$HOST/api/v0/version" 2>/dev/null; then
+		break
+	fi
+	sleep 0.5
+done
+# Re-login: the bus restart minted a new daemon process, so the
+# token from before the bounce is unrelated (its rate-limit bucket
+# is empty too).
+ADMIN_TOKEN=$(curl -s -X POST -H "Content-Type: application/json" \
+	-d "{\"password\":\"$ADMIN_PASS\"}" "$HOST/api/v0/auth/login?type=bearer" | jq -r .token)
+[ -n "$ADMIN_TOKEN" ] && [ "$ADMIN_TOKEN" != "null" ] || _die "admin login failed after bounce"
+
+# Let the refresher fill the ring with enough events that
+# OldestId starts climbing — required for the gap case below. With
+# the bus at 32 slots, a few ticks of server / client / download
+# churn are enough.
+sleep 8
+
+# --- 1. resync(reason=gap) — Last-Event-ID below OldestId. -------
+#
+# After 8 s of refresher ticks the 32-slot ring has rotated past
+# id 1, so `Last-Event-ID: 1` is in the gap range. Expect the
+# synthetic `resync` event first.
+: > "$SSE"
+(curl -s -m 3 -N \
+	-H "Last-Event-ID: 1" \
+	-H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/events" >> "$SSE" 2>&1) &
+PID=$!
+sleep 2.5
+kill $PID 2>/dev/null
+wait $PID 2>/dev/null
+
+if grep -q "^event: resync$" "$SSE"; then
+	_pass "resync event fires when Last-Event-ID is below OldestId"
+else
+	_fail "resync(gap) event" \
+		"no 'event: resync' line in stream; sample: $(head -20 "$SSE")"
+fi
+
+# Payload should be JSON with reason=gap, since_id=1, newest_id>0.
+RESYNC_DATA=$(grep -A2 "^event: resync$" "$SSE" \
+	| grep "^data: " | head -1 | sed 's/^data: //')
+if [ -n "$RESYNC_DATA" ]; then
+	REASON=$(echo "$RESYNC_DATA" | jq -r .reason 2>/dev/null)
+	SINCE=$(echo "$RESYNC_DATA" | jq -r .since_id 2>/dev/null)
+	NEWEST=$(echo "$RESYNC_DATA" | jq -r .newest_id 2>/dev/null)
+	if [ "$REASON" = "gap" ]; then
+		_pass "resync.reason == 'gap'"
+	else
+		_fail "resync.reason for gap case" "expected 'gap', got '$REASON' from $RESYNC_DATA"
+	fi
+	if [ "$SINCE" = "1" ]; then
+		_pass "resync.since_id echoes the client-sent Last-Event-ID"
+	else
+		_fail "resync.since_id" "expected 1, got '$SINCE'"
+	fi
+	if [ -n "$NEWEST" ] && [ "$NEWEST" != "null" ] && [ "$NEWEST" -gt 0 ] 2>/dev/null; then
+		_pass "resync.newest_id is a positive integer ($NEWEST)"
+	else
+		_fail "resync.newest_id" "expected positive int, got '$NEWEST'"
+	fi
+else
+	_fail "resync data line" "no 'data:' line under resync event in $SSE"
+fi
+
+# Phase 8c's `: replay-gap` comment must NOT appear anymore —
+# replaced by the typed event.
+if grep -q "^: replay-gap$" "$SSE"; then
+	_fail "Phase 8c comment is gone" \
+		"': replay-gap' comment still appears alongside resync event — should be removed"
+else
+	_pass "Phase 8c ': replay-gap' comment is no longer emitted"
+fi
+
+# --- 2. resync(reason=restart) — Last-Event-ID above NewestId. ---
+: > "$SSE"
+(curl -s -m 3 -N \
+	-H "Last-Event-ID: 999999999999" \
+	-H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/events" >> "$SSE" 2>&1) &
+PID=$!
+sleep 2.5
+kill $PID 2>/dev/null
+wait $PID 2>/dev/null
+
+if grep -q "^event: resync$" "$SSE"; then
+	_pass "resync event fires when Last-Event-ID is above NewestId"
+else
+	_fail "resync(restart) event" \
+		"no 'event: resync' line; sample: $(head -10 "$SSE")"
+fi
+RESYNC_DATA=$(grep -A2 "^event: resync$" "$SSE" \
+	| grep "^data: " | head -1 | sed 's/^data: //')
+REASON=$(echo "$RESYNC_DATA" | jq -r .reason 2>/dev/null)
+if [ "$REASON" = "restart" ]; then
+	_pass "resync.reason == 'restart' for above-NewestId case"
+else
+	_fail "resync.reason for restart case" \
+		"expected 'restart', got '$REASON' from $RESYNC_DATA"
+fi
+
+# --- 3. resync.id == newest_id so the client's next reconnect ----
+#     resumes from the high water (no resync loop).
+RESYNC_ID=$(grep -B1 "^data: {.reason" "$SSE" | grep "^id: " | head -1 | sed 's/^id: //')
+NEWEST_FROM_PAYLOAD=$(echo "$RESYNC_DATA" | jq -r .newest_id 2>/dev/null)
+if [ -n "$RESYNC_ID" ] && [ "$RESYNC_ID" = "$NEWEST_FROM_PAYLOAD" ]; then
+	_pass "resync event id == newest_id ($RESYNC_ID) — no resync loop on next reconnect"
+else
+	_fail "resync event id matches newest_id" \
+		"frame id='$RESYNC_ID' payload newest_id='$NEWEST_FROM_PAYLOAD' — must match"
+fi
+
+# --- 4. log_appended — best-effort: trigger via POST /downloads. -
+#
+# amuled logs sparsely during normal operation, so this test is
+# best-effort. If no log_appended fires within the window we SKIP
+# rather than fail (EventDiffTest covers the wiring deterministically).
+# When the event DOES fire, validate the payload shape.
+
+# First clear any prior in-queue test artifact so the POST
+# below actually does work (and potentially logs).
+TEST_HASH="0031c9cba65c50dd2015c184b2ca2c88"
+TEST_LINK="ed2k://|file|ubuntu-24.04.4-desktop-amd64.iso|6655619072|0031C9CBA65C50DD2015C184B2CA2C88|/"
+curl -s -X DELETE -H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/downloads/$TEST_HASH" > /dev/null 2>&1 || true
+sleep 3
+
+: > "$SSE"
+(curl -s -m 14 -N \
+	-H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/events" >> "$SSE" 2>&1) &
+PID=$!
+sleep 2
+curl -s -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
+	-H "Content-Type: application/json" \
+	-d "{\"ed2k_link\":\"$TEST_LINK\"}" \
+	"$HOST/api/v0/downloads" > /dev/null
+sleep 11
+kill $PID 2>/dev/null
+wait $PID 2>/dev/null
+
+LOG_EVENT_COUNT=$(grep -c "^event: log_appended$" "$SSE" || true)
+if [ "$LOG_EVENT_COUNT" -ge 1 ]; then
+	_pass "log_appended event observed ($LOG_EVENT_COUNT events) — wire path confirmed"
+	# Validate payload shape: must have a .lines array of strings.
+	LOG_DATA=$(grep -A2 "^event: log_appended$" "$SSE" \
+		| grep "^data: " | head -1 | sed 's/^data: //')
+	if echo "$LOG_DATA" | jq -e '.lines | type == "array"' >/dev/null 2>&1; then
+		_pass "log_appended.data.lines is an array"
+	else
+		_fail "log_appended payload shape" \
+			"expected {lines:[...]}, got: $LOG_DATA"
+	fi
+	if echo "$LOG_DATA" | jq -e '.lines | length > 0' >/dev/null 2>&1; then
+		_pass "log_appended.data.lines is non-empty"
+	else
+		_fail "log_appended.data.lines length" \
+			"empty lines array — refresher fired the event with no new lines"
+	fi
+else
+	_skip "log_appended observable in smoke window (amuled logs are sparse; EventDiffTest covers the wiring)"
+fi
+
+# --- Summary. -----------------------------------------------------
+echo
+if [ "$FAIL_COUNT" -eq 0 ]; then
+	echo "OK: $TEST_COUNT/$TEST_COUNT passed"
+	exit 0
+fi
+echo "FAIL: $FAIL_COUNT/$TEST_COUNT failed"
+exit 1
diff --git a/unittests/curl-tests/amuleapi/25-cors.sh b/unittests/curl-tests/amuleapi/25-cors.sh
new file mode 100755
index 0000000000..ff3596d6e4
--- /dev/null
+++ b/unittests/curl-tests/amuleapi/25-cors.sh
@@ -0,0 +1,326 @@
+#!/usr/bin/env bash
+#
+# amuleapi 25-cors — CORS opt-in.
+#
+# Wire contract:
+#   * `AllowCORS=0` (default): no `Access-Control-*` headers on any
+#     response. Browser cross-origin fetches blocked by the browser
+#     per same-origin policy. `Vary: Origin` NOT set.
+#   * `AllowCORS=1` + empty `CorsOriginAllowlist`: wildcard via echo.
+#     Any request that carries an `Origin` header gets that origin
+#     echoed in `Access-Control-Allow-Origin`. `Vary: Origin` is
+#     always set so caches don't poison cross-origin responses.
+#   * `AllowCORS=1` + non-empty `CorsOriginAllowlist`: an origin is
+#     echoed only if it appears verbatim in the comma-separated
+#     allowlist. Non-matching origins receive `Vary: Origin` but
+#     no `Access-Control-Allow-Origin`.
+#   * Credentials: when an origin is allowed,
+#     `Access-Control-Allow-Credentials: true` is always set
+#     (cookie-auth-compatible with the per-origin echo).
+#   * Preflight: `OPTIONS` + `Access-Control-Request-Method` short-
+#     circuits before auth, replies 204 with
+#     `Access-Control-Allow-Methods: GET, HEAD, POST, PATCH, DELETE,
+#     OPTIONS` and `Access-Control-Allow-Headers: Authorization,
+#     Content-Type, If-None-Match, Last-Event-ID` and
+#     `Access-Control-Max-Age: 86400`.
+#   * SSE: the streaming response carries the same Allow-Origin /
+#     Allow-Credentials / Vary headers.
+
+set -u
+set -o pipefail
+
+HOST=${HOST:-localhost:4713}
+ADMIN_PASS=${ADMIN_PASS:-adminpass}
+CONFIG_DIR=${AMULEAPI_CONFIG_DIR:-/tmp/amuleapi-regtest}
+BIN=${AMULEAPI_BIN:-/Users/bitandyou/Sync/Utility/PlexBox/amule/amule-fiber/amule-src-amuleapi/build-macos/src/webapi/amuleapi}
+LOG=${AMULEAPI_LOG:-/tmp/amuleapi.log}
+
+FAIL_COUNT=0
+TEST_COUNT=0
+
+HDR=$(mktemp -t amuleapi_25_cors_hdr.XXXXXX)
+BODY=$(mktemp -t amuleapi_25_cors_body.XXXXXX)
+SSE=$(mktemp -t amuleapi_25_cors_sse.XXXXXX)
+trap 'rm -f "$HDR" "$BODY" "$SSE"' EXIT
+
+_die()  { echo "FATAL: $*" >&2; exit 2; }
+_pass() { TEST_COUNT=$((TEST_COUNT+1)); echo "  PASS  $1"; }
+_fail() {
+	TEST_COUNT=$((TEST_COUNT+1)); FAIL_COUNT=$((FAIL_COUNT+1))
+	echo "  FAIL  $1"
+	shift
+	for arg in "$@"; do echo "        $arg"; done
+}
+
+if ! command -v jq >/dev/null 2>&1; then _die "jq is required."; fi
+if ! curl -s -o /dev/null --max-time 2 "$HOST/api/v0/version" 2>/dev/null; then
+	_die "amuleapi at $HOST is not reachable."
+fi
+if [ ! -x "$BIN" ]; then
+	_die "amuleapi binary not found at $BIN. Set AMULEAPI_BIN to override."
+fi
+
+echo "amuleapi 25-cors smoke @ $HOST (bin=$BIN config=$CONFIG_DIR)"
+
+# Helper: rewrite amuleapi.conf with a given AllowCORS value and
+# allowlist, then bounce the daemon. The first three sections are
+# the defaults the orchestrator wrote; we only mutate [Server] so
+# password files and the JWT secret stay valid across the restart.
+_rewrite_cors_and_restart() {
+	local allow=$1
+	local allowlist=$2
+	pkill -f "amuleapi --config-dir=$CONFIG_DIR" 2>/dev/null
+	sleep 1
+	cat > "$CONFIG_DIR/amuleapi.conf" <<EOF
+[Server]
+BindAddress=127.0.0.1
+Port=4713
+AllowCORS=$allow
+CorsOriginAllowlist=$allowlist
+
+[EC]
+Host=127.0.0.1
+Port=4712
+Password=
+
+[Auth]
+LoginFailureWindowSeconds=60
+LoginFailureThreshold=5
+LoginLockoutSeconds=300
+EOF
+	"$BIN" --config-dir="$CONFIG_DIR" \
+		--host=127.0.0.1 --port=4712 --password=amule \
+		> "$LOG" 2>&1 &
+	# Wait for /version to respond.
+	for _ in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15; do
+		if curl -s -o /dev/null --max-time 1 "$HOST/api/v0/version" 2>/dev/null; then
+			return 0
+		fi
+		sleep 0.5
+	done
+	_die "daemon did not come back up after restart (allow=$allow allowlist=$allowlist)"
+}
+
+# Helper: capture status + headers + body of an arbitrary curl.
+# Args: extra curl args. Result: HDR + BODY temp files populated.
+_curl() {
+	: > "$HDR"; : > "$BODY"
+	curl -sS -o "$BODY" -D "$HDR" "$@" || true
+}
+
+# Helper: case-insensitive header lookup against HDR file.
+# Returns the trimmed value of the first matching header.
+_hdr() {
+	local name=$1
+	# Strip CRLF and leading "name:" with case-insensitive match.
+	awk -v n="$name" '
+		BEGIN { IGNORECASE = 1 }
+		match($0, "^"n"[: ]+") {
+			v = substr($0, RSTART + RLENGTH);
+			sub(/\r$/, "", v);
+			sub(/^[[:space:]]+/, "", v);
+			print v;
+			exit
+		}
+	' "$HDR"
+}
+
+# --- Mode A: AllowCORS=0 (default). ------------------------------
+_rewrite_cors_and_restart 0 ""
+
+_curl -H "Origin: https://app.example.com" "$HOST/api/v0/version"
+ACAO=$(_hdr "Access-Control-Allow-Origin")
+VARY=$(_hdr "Vary")
+if [ -z "$ACAO" ]; then
+	_pass "AllowCORS=0: no Access-Control-Allow-Origin on response"
+else
+	_fail "AllowCORS=0 leaks Access-Control-Allow-Origin" "got: $ACAO"
+fi
+if [ -z "$VARY" ] || ! echo "$VARY" | grep -qi "Origin"; then
+	_pass "AllowCORS=0: no Vary: Origin on response"
+else
+	_fail "AllowCORS=0 leaks Vary: Origin" "got: $VARY"
+fi
+
+# --- Mode B: AllowCORS=1 with empty allowlist (wildcard). --------
+_rewrite_cors_and_restart 1 ""
+
+_curl -H "Origin: https://wild.example.com" "$HOST/api/v0/version"
+ACAO=$(_hdr "Access-Control-Allow-Origin")
+ACAC=$(_hdr "Access-Control-Allow-Credentials")
+ACEH=$(_hdr "Access-Control-Expose-Headers")
+VARY=$(_hdr "Vary")
+if [ "$ACAO" = "https://wild.example.com" ]; then
+	_pass "AllowCORS=1 (wildcard): Access-Control-Allow-Origin echoes the Origin verbatim"
+else
+	_fail "Wildcard echo" "expected 'https://wild.example.com', got '$ACAO'"
+fi
+if [ "$ACAC" = "true" ]; then
+	_pass "AllowCORS=1: Access-Control-Allow-Credentials: true"
+else
+	_fail "Allow-Credentials" "expected 'true', got '$ACAC'"
+fi
+if echo "$ACEH" | grep -qi "ETag"; then
+	_pass "AllowCORS=1: Access-Control-Expose-Headers lists ETag"
+else
+	_fail "Expose-Headers" "expected to contain ETag, got '$ACEH'"
+fi
+if echo "$VARY" | grep -qi "Origin"; then
+	_pass "AllowCORS=1: Vary: Origin set"
+else
+	_fail "Vary: Origin" "expected 'Origin', got '$VARY'"
+fi
+
+# Same daemon, but request without an Origin header. The server
+# should NOT add Access-Control-Allow-Origin (no origin to echo)
+# but SHOULD still set Vary: Origin (CORS is on).
+_curl "$HOST/api/v0/version"
+ACAO=$(_hdr "Access-Control-Allow-Origin")
+VARY=$(_hdr "Vary")
+if [ -z "$ACAO" ]; then
+	_pass "AllowCORS=1: request without Origin → no Allow-Origin"
+else
+	_fail "Spurious Allow-Origin" "no Origin sent, but got: $ACAO"
+fi
+if echo "$VARY" | grep -qi "Origin"; then
+	_pass "AllowCORS=1: Vary: Origin set even when request has no Origin"
+else
+	_fail "Vary: Origin when CORS on" "got: $VARY"
+fi
+
+# --- Mode C: AllowCORS=1 with a per-origin allowlist. ------------
+_rewrite_cors_and_restart 1 "https://allowed.example.com,https://also.example.com"
+
+_curl -H "Origin: https://allowed.example.com" "$HOST/api/v0/version"
+ACAO=$(_hdr "Access-Control-Allow-Origin")
+if [ "$ACAO" = "https://allowed.example.com" ]; then
+	_pass "Allowlist: matching Origin echoes back"
+else
+	_fail "Allowlist match" "expected echo, got '$ACAO'"
+fi
+
+_curl -H "Origin: https://also.example.com" "$HOST/api/v0/version"
+ACAO=$(_hdr "Access-Control-Allow-Origin")
+if [ "$ACAO" = "https://also.example.com" ]; then
+	_pass "Allowlist: second entry matches and echoes"
+else
+	_fail "Allowlist second entry" "expected echo, got '$ACAO'"
+fi
+
+_curl -H "Origin: https://attacker.example.com" "$HOST/api/v0/version"
+ACAO=$(_hdr "Access-Control-Allow-Origin")
+VARY=$(_hdr "Vary")
+if [ -z "$ACAO" ]; then
+	_pass "Allowlist: non-matching Origin → no Allow-Origin"
+else
+	_fail "Allowlist rejects" "expected no Allow-Origin, got '$ACAO'"
+fi
+if echo "$VARY" | grep -qi "Origin"; then
+	_pass "Allowlist: Vary: Origin set even on rejected origin"
+else
+	_fail "Vary on rejection" "got: $VARY"
+fi
+
+# --- OPTIONS preflight (Mode C, allowed origin). -----------------
+_curl -X OPTIONS \
+	-H "Origin: https://allowed.example.com" \
+	-H "Access-Control-Request-Method: POST" \
+	-H "Access-Control-Request-Headers: Authorization, Content-Type" \
+	"$HOST/api/v0/downloads"
+STATUS=$(head -1 "$HDR" | awk '{print $2}')
+ACAO=$(_hdr "Access-Control-Allow-Origin")
+ACAM=$(_hdr "Access-Control-Allow-Methods")
+ACAH=$(_hdr "Access-Control-Allow-Headers")
+ACMA=$(_hdr "Access-Control-Max-Age")
+
+if [ "$STATUS" = "204" ]; then
+	_pass "Preflight OPTIONS → 204"
+else
+	_fail "Preflight status" "expected 204, got '$STATUS'"
+fi
+if [ "$ACAO" = "https://allowed.example.com" ]; then
+	_pass "Preflight: Allow-Origin echoes allowed origin"
+else
+	_fail "Preflight Allow-Origin" "expected echo, got '$ACAO'"
+fi
+if echo "$ACAM" | grep -q "POST" && echo "$ACAM" | grep -q "PATCH" \
+   && echo "$ACAM" | grep -q "DELETE"; then
+	_pass "Preflight: Allow-Methods lists mutating verbs"
+else
+	_fail "Allow-Methods" "expected POST/PATCH/DELETE listed, got '$ACAM'"
+fi
+if echo "$ACAH" | grep -qi "Authorization" \
+   && echo "$ACAH" | grep -qi "If-None-Match" \
+   && echo "$ACAH" | grep -qi "Last-Event-ID"; then
+	_pass "Preflight: Allow-Headers lists Authorization, If-None-Match, Last-Event-ID"
+else
+	_fail "Allow-Headers" "missing one of the expected headers, got '$ACAH'"
+fi
+if [ "$ACMA" = "86400" ]; then
+	_pass "Preflight: Max-Age == 86400 (24h preflight cache)"
+else
+	_fail "Max-Age" "expected 86400, got '$ACMA'"
+fi
+
+# Preflight from a non-allowed origin: 204 with no Allow-Origin.
+# Browser will then block the actual request.
+_curl -X OPTIONS \
+	-H "Origin: https://attacker.example.com" \
+	-H "Access-Control-Request-Method: POST" \
+	"$HOST/api/v0/downloads"
+STATUS=$(head -1 "$HDR" | awk '{print $2}')
+ACAO=$(_hdr "Access-Control-Allow-Origin")
+if [ "$STATUS" = "204" ] && [ -z "$ACAO" ]; then
+	_pass "Preflight (non-allowed origin) → 204 with no Allow-Origin"
+else
+	_fail "Preflight rejection" \
+		"expected 204 + no Allow-Origin, got status='$STATUS' Allow-Origin='$ACAO'"
+fi
+
+# --- SSE response CORS headers (mode C, allowed origin). ---------
+#
+# Mode C is still active. Capture only the response head — we don't
+# need the stream body for header verification. Curl handles SSE
+# the same as any HTTP/1.1 chunked response; -I won't work because
+# HEAD doesn't trigger the streaming handler, so we do a short -m 2.
+: > "$HDR"; : > "$SSE"
+ADMIN_TOKEN=$(curl -s -X POST -H "Content-Type: application/json" \
+	-d "{\"password\":\"$ADMIN_PASS\"}" "$HOST/api/v0/auth/login?type=bearer" | jq -r .token)
+[ -n "$ADMIN_TOKEN" ] && [ "$ADMIN_TOKEN" != "null" ] || _die "admin login failed"
+curl -sS -m 2 -D "$HDR" -o "$SSE" \
+	-H "Origin: https://allowed.example.com" \
+	-H "Authorization: Bearer $ADMIN_TOKEN" \
+	"$HOST/api/v0/events" >/dev/null 2>&1 || true
+ACAO=$(_hdr "Access-Control-Allow-Origin")
+ACAC=$(_hdr "Access-Control-Allow-Credentials")
+CT=$(_hdr "Content-Type")
+if [ "$ACAO" = "https://allowed.example.com" ]; then
+	_pass "SSE response: Allow-Origin set for allowed origin"
+else
+	_fail "SSE Allow-Origin" "expected echo, got '$ACAO'"
+fi
+if [ "$ACAC" = "true" ]; then
+	_pass "SSE response: Allow-Credentials: true"
+else
+	_fail "SSE Allow-Credentials" "expected 'true', got '$ACAC'"
+fi
+if echo "$CT" | grep -qi "text/event-stream"; then
+	_pass "SSE response: Content-Type unchanged by CORS path"
+else
+	_fail "SSE Content-Type" "expected text/event-stream, got '$CT'"
+fi
+
+# --- Cleanup: restore AllowCORS=0 so subsequent manual smokes don't
+#     inherit phase 9's CORS-enabled config when re-run in the same
+#     /tmp/amuleapi-regtest. run-all.sh wipes between phases anyway,
+#     but this protects standalone invocations.
+_rewrite_cors_and_restart 0 ""
+
+# --- Summary. -----------------------------------------------------
+echo
+if [ "$FAIL_COUNT" -eq 0 ]; then
+	echo "OK: $TEST_COUNT/$TEST_COUNT passed"
+	exit 0
+fi
+echo "FAIL: $FAIL_COUNT/$TEST_COUNT failed"
+exit 1
diff --git a/unittests/curl-tests/amuleapi/26-rfc-followup-endpoints.sh b/unittests/curl-tests/amuleapi/26-rfc-followup-endpoints.sh
new file mode 100755
index 0000000000..711a743606
--- /dev/null
+++ b/unittests/curl-tests/amuleapi/26-rfc-followup-endpoints.sh
@@ -0,0 +1,413 @@
+#!/usr/bin/env bash
+#
+# amuleapi 26-rfc-followup-endpoints — endpoints added to align with the RFC PR #132
+# review:
+#
+#   * GET    /status                       — `kad.network: {users,files,nodes}` rollup
+#   * POST   /shared/reload                — rescan share roots
+#   * POST   /servers/update               — refresh server list from server.met URL
+#   * POST   /servers/<ip>:<port>/connect  — address-keyed alias
+#   * DELETE /servers/<ip>:<port>          — address-keyed alias
+#   * DELETE /logs/amule                   — clear amule log + in-process cache
+#   * DELETE /logs/serverinfo              — clear MOTD log + invalidate lazy cache
+#   * POST   /downloads {"links":[...]}    — array body, alongside `ed2k_link`
+#   * POST   /networks/disconnect          — `{"network":"ed2k"|"kad"|"both"}` selector
+#   * GET    /clients?filter=uploads|downloads|active
+#   * GET    /events?channels=<csv>        — subscribe to a subset of event types
+#
+# All log-mutating tests verify that a *fast* GET immediately after the
+# mutation returns post-mutation state (not stale cache).
+
+set -u
+set -o pipefail
+
+HOST=${HOST:-localhost:4713}
+ADMIN_PASS=${ADMIN_PASS:-adminpass}
+
+TEST_HASH="0031c9cba65c50dd2015c184b2ca2c88"
+TEST_LINK="ed2k://|file|ubuntu-24.04.4-desktop-amd64.iso|6655619072|0031C9CBA65C50DD2015C184B2CA2C88|/"
+
+FAIL_COUNT=0
+TEST_COUNT=0
+SSE=$(mktemp -t amuleapi_26_rfc_followup_endpoints_sse.XXXXXX)
+trap '
+	rm -f "$SSE"
+	# Best-effort: delete any partfile this script may have left in
+	# amuled queue (Windows VM has ~63 GB on C: — a leftover 6.6 GB
+	# Ubuntu ISO partfile blocks the next run). Errors swallowed
+	# because the daemon may already be down on a CI tear-down.
+	if [ -n "${ADMIN_TOKEN:-}" ]; then
+		curl -s -X DELETE -H "Authorization: Bearer $ADMIN_TOKEN" \
+			"$HOST/api/v0/downloads/$TEST_HASH" > /dev/null 2>&1 || true
+	fi
+' EXIT
+
+_die()  { echo "FATAL: $*" >&2; exit 2; }
+_pass() { TEST_COUNT=$((TEST_COUNT+1)); echo "  PASS  $1"; }
+_skip() { TEST_COUNT=$((TEST_COUNT+1)); echo "  SKIP  $1"; }
+_fail() {
+	TEST_COUNT=$((TEST_COUNT+1)); FAIL_COUNT=$((FAIL_COUNT+1))
+	echo "  FAIL  $1"
+	shift
+	for arg in "$@"; do echo "        $arg"; done
+}
+
+if ! command -v jq >/dev/null 2>&1; then _die "jq is required."; fi
+if ! curl -s -o /dev/null --max-time 2 "$HOST/api/v0/version"; then
+	_die "amuleapi at $HOST is not reachable."
+fi
+
+echo "amuleapi 26-rfc-followup-endpoints smoke @ $HOST"
+
+ADMIN_TOKEN=$(curl -s -X POST -H "Content-Type: application/json" \
+	-d "{\"password\":\"$ADMIN_PASS\"}" "$HOST/api/v0/auth/login?type=bearer" | jq -r .token)
+[ -n "$ADMIN_TOKEN" ] && [ "$ADMIN_TOKEN" != "null" ] || _die "admin login failed"
+H_AUTH=(-H "Authorization: Bearer $ADMIN_TOKEN")
+sleep 4
+
+# --- 1. /status kad.network rollup. ------------------------------
+STATUS=$(curl -s "${H_AUTH[@]}" "$HOST/api/v0/status")
+if echo "$STATUS" | jq -e '.kad.network | type == "object"' >/dev/null 2>&1; then
+	_pass "/status .kad.network exists"
+else
+	_fail "/status kad.network" "missing: $(echo "$STATUS" | jq -c .kad)"
+fi
+for f in users files nodes; do
+	if echo "$STATUS" | jq -e ".kad.network.$f | type == \"number\"" >/dev/null 2>&1; then
+		_pass "/status .kad.network.$f is a number"
+	else
+		_fail "/status kad.network.$f" "missing/non-numeric"
+	fi
+done
+
+# --- 2. POST /shared/reload. -------------------------------------
+RC=$(curl -s -o /tmp/p11_shared_reload.json -w "%{http_code}" -X POST "${H_AUTH[@]}" \
+	"$HOST/api/v0/shared/reload")
+if [ "$RC" = "202" ]; then
+	_pass "POST /shared/reload → 202"
+else
+	_fail "shared/reload status" "expected 202, got $RC: $(cat /tmp/p11_shared_reload.json)"
+fi
+if jq -e '.ok == true' /tmp/p11_shared_reload.json >/dev/null 2>&1; then
+	_pass "POST /shared/reload .ok == true"
+else
+	_fail "shared/reload body" "$(cat /tmp/p11_shared_reload.json)"
+fi
+
+# --- 3. POST /servers/update — body validation. ------------------
+RC=$(curl -s -o /tmp/p11_su.json -w "%{http_code}" -X POST "${H_AUTH[@]}" \
+	-H "Content-Type: application/json" -d '{}' "$HOST/api/v0/servers/update")
+if [ "$RC" = "400" ]; then
+	_pass "POST /servers/update missing url → 400"
+else
+	_fail "servers/update no-body" "expected 400, got $RC"
+fi
+RC=$(curl -s -o /tmp/p11_su.json -w "%{http_code}" -X POST "${H_AUTH[@]}" \
+	-H "Content-Type: application/json" \
+	-d '{"servers_url":"ftp://nope"}' "$HOST/api/v0/servers/update")
+if [ "$RC" = "400" ]; then
+	_pass "POST /servers/update non-http url → 400"
+else
+	_fail "servers/update bad url" "expected 400, got $RC"
+fi
+RC=$(curl -s -o /tmp/p11_su.json -w "%{http_code}" -X POST "${H_AUTH[@]}" \
+	-H "Content-Type: application/json" \
+	-d '{"servers_url":"http://upd.emule-security.org/server.met"}' \
+	"$HOST/api/v0/servers/update")
+if [ "$RC" = "202" ]; then
+	_pass "POST /servers/update valid url → 202"
+else
+	_fail "servers/update happy path" "got $RC: $(cat /tmp/p11_su.json)"
+fi
+
+# --- 4. /servers/<ip>:<port>/connect + DELETE alias. -------------
+# 404 path is always testable.
+RC=$(curl -s -o /dev/null -w "%{http_code}" -X POST "${H_AUTH[@]}" \
+	"$HOST/api/v0/servers/0.0.0.0:1/connect")
+if [ "$RC" = "404" ]; then
+	_pass "POST /servers/<bogus-ip:port>/connect → 404"
+else
+	_fail "address alias 404" "expected 404, got $RC"
+fi
+RC=$(curl -s -o /dev/null -w "%{http_code}" -X DELETE "${H_AUTH[@]}" \
+	"$HOST/api/v0/servers/0.0.0.0:1")
+if [ "$RC" = "404" ]; then
+	_pass "DELETE /servers/<bogus-ip:port> → 404"
+else
+	_fail "address alias DELETE 404" "expected 404, got $RC"
+fi
+# Positive path: only test if there's actually a server in the cache.
+# The address field is the canonical "<ip-or-hostname>:<port>" string
+# the daemon reports, so we use it verbatim (no need to convert the
+# numeric `ip` field — `address` is the operator-meaningful form).
+ADDR=$(curl -s "${H_AUTH[@]}" "$HOST/api/v0/servers" \
+	| jq -r '.servers[0].address // empty')
+if [ -n "$ADDR" ] && [ "$ADDR" != "null" ]; then
+	RC=$(curl -s -o /dev/null -w "%{http_code}" -X POST "${H_AUTH[@]}" \
+		"$HOST/api/v0/servers/$ADDR/connect")
+	if [ "$RC" = "202" ] || [ "$RC" = "200" ]; then
+		_pass "POST /servers/$ADDR/connect resolves alias and accepts ($RC)"
+	else
+		_fail "address alias connect" "expected 200/202, got $RC"
+	fi
+else
+	_skip "address-keyed server connect (no servers in cache)"
+fi
+
+# --- 5. DELETE /logs/amule + freshness. --------------------------
+RC=$(curl -s -o /dev/null -w "%{http_code}" -X DELETE "${H_AUTH[@]}" \
+	"$HOST/api/v0/logs/amule")
+if [ "$RC" = "204" ]; then
+	_pass "DELETE /logs/amule → 204"
+else
+	_fail "logs/amule DELETE" "expected 204, got $RC"
+fi
+# Fast GET immediately after — must show empty / post-reset state.
+GET_BODY=$(curl -s "${H_AUTH[@]}" "$HOST/api/v0/logs/amule")
+LINES=$(echo "$GET_BODY" | jq -r '.lines | length' 2>/dev/null)
+TOTAL=$(echo "$GET_BODY" | jq -r '.total_cached' 2>/dev/null)
+if [ "$LINES" = "0" ] && [ "$TOTAL" = "0" ]; then
+	_pass "GET /logs/amule immediately after DELETE returns empty (no stale cache)"
+else
+	_fail "logs/amule post-DELETE freshness" \
+		"lines=$LINES total=$TOTAL — expected 0/0"
+fi
+
+# --- 6. DELETE /logs/serverinfo + freshness (lazy cache!). -------
+RC=$(curl -s -o /dev/null -w "%{http_code}" -X DELETE "${H_AUTH[@]}" \
+	"$HOST/api/v0/logs/serverinfo")
+if [ "$RC" = "204" ]; then
+	_pass "DELETE /logs/serverinfo → 204"
+else
+	_fail "logs/serverinfo DELETE" "expected 204, got $RC"
+fi
+# Fast GET immediately after — must show empty / post-reset.
+GET_BODY=$(curl -s "${H_AUTH[@]}" "$HOST/api/v0/logs/serverinfo")
+BYTES=$(echo "$GET_BODY" | jq -r '.total_bytes' 2>/dev/null)
+if [ "$BYTES" = "0" ]; then
+	_pass "GET /logs/serverinfo immediately after DELETE returns empty (lazy cache invalidated)"
+else
+	_fail "logs/serverinfo post-DELETE freshness" \
+		"total_bytes=$BYTES — expected 0"
+fi
+
+# --- 7. POST /downloads array body shape. ------------------------
+# Cleanup any prior queue entry to make the test deterministic.
+# A robust cleanup tries the DELETE, then waits until the file is
+# really gone from /downloads (amuled processes DELETE asynchronously
+# — the entry stays around for one or two refresher ticks while the
+# partfile is unmapped). Without this, the next POST returns
+# "Invalid link or already on list" and the test misreads the
+# wire shape verdict.
+_wait_for_no_download() {
+	for _ in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15; do
+		local present=$(curl -s "${H_AUTH[@]}" "$HOST/api/v0/downloads" \
+			| jq -r --arg h "$TEST_HASH" \
+				'.downloads | map(select(.hash == $h)) | length')
+		if [ "$present" = "0" ]; then return 0; fi
+		sleep 1
+	done
+	return 1
+}
+curl -s -X DELETE "${H_AUTH[@]}" "$HOST/api/v0/downloads/$TEST_HASH" > /dev/null
+_wait_for_no_download || true
+
+# Array form
+RC=$(curl -s -o /tmp/p11_dl.json -w "%{http_code}" -X POST "${H_AUTH[@]}" \
+	-H "Content-Type: application/json" \
+	-d "{\"links\":[\"$TEST_LINK\"]}" "$HOST/api/v0/downloads")
+if [ "$RC" = "202" ]; then
+	_pass "POST /downloads array form → 202"
+else
+	_fail "downloads array status" "expected 202, got $RC: $(cat /tmp/p11_dl.json)"
+fi
+if jq -e '.accepted == 1 and .failed == 0' /tmp/p11_dl.json >/dev/null 2>&1; then
+	_pass "POST /downloads array reports accepted=1, failed=0"
+else
+	_fail "downloads array counts" "$(cat /tmp/p11_dl.json)"
+fi
+# Mixing both forms → 400
+RC=$(curl -s -o /dev/null -w "%{http_code}" -X POST "${H_AUTH[@]}" \
+	-H "Content-Type: application/json" \
+	-d "{\"ed2k_link\":\"$TEST_LINK\",\"links\":[\"$TEST_LINK\"]}" \
+	"$HOST/api/v0/downloads")
+if [ "$RC" = "400" ]; then
+	_pass "POST /downloads mixing ed2k_link AND links → 400"
+else
+	_fail "downloads mixed body" "expected 400, got $RC"
+fi
+# Backwards-compat singular form still works.
+curl -s -X DELETE "${H_AUTH[@]}" "$HOST/api/v0/downloads/$TEST_HASH" > /dev/null
+_wait_for_no_download || true
+RC=$(curl -s -o /dev/null -w "%{http_code}" -X POST "${H_AUTH[@]}" \
+	-H "Content-Type: application/json" \
+	-d "{\"ed2k_link\":\"$TEST_LINK\"}" "$HOST/api/v0/downloads")
+if [ "$RC" = "202" ]; then
+	_pass "POST /downloads singular ed2k_link still accepted (backwards-compat)"
+else
+	_fail "downloads singular body" "expected 202, got $RC"
+fi
+
+# --- 8. POST /networks/disconnect selector. ----------------------
+# Default (no body) = both
+RC=$(curl -s -o /tmp/p11_nd.json -w "%{http_code}" -X POST "${H_AUTH[@]}" \
+	"$HOST/api/v0/networks/disconnect")
+if [ "$RC" = "200" ]; then
+	_pass "POST /networks/disconnect (no body) → 200 default=both"
+else
+	_fail "networks disconnect no-body" "expected 200, got $RC"
+fi
+sleep 2
+# selector=ed2k
+RC=$(curl -s -o /dev/null -w "%{http_code}" -X POST "${H_AUTH[@]}" \
+	-H "Content-Type: application/json" \
+	-d '{"network":"ed2k"}' "$HOST/api/v0/networks/disconnect")
+if [ "$RC" = "200" ]; then
+	_pass "POST /networks/disconnect {\"network\":\"ed2k\"} → 200"
+else
+	_fail "networks disconnect ed2k" "expected 200, got $RC"
+fi
+sleep 1
+# selector=kad
+RC=$(curl -s -o /dev/null -w "%{http_code}" -X POST "${H_AUTH[@]}" \
+	-H "Content-Type: application/json" \
+	-d '{"network":"kad"}' "$HOST/api/v0/networks/disconnect")
+if [ "$RC" = "200" ]; then
+	_pass "POST /networks/disconnect {\"network\":\"kad\"} → 200"
+else
+	_fail "networks disconnect kad" "expected 200, got $RC"
+fi
+# Invalid selector
+RC=$(curl -s -o /dev/null -w "%{http_code}" -X POST "${H_AUTH[@]}" \
+	-H "Content-Type: application/json" \
+	-d '{"network":"icq"}' "$HOST/api/v0/networks/disconnect")
+if [ "$RC" = "400" ]; then
+	_pass "POST /networks/disconnect bogus selector → 400"
+else
+	_fail "networks disconnect bogus" "expected 400, got $RC"
+fi
+
+# --- 9. /clients filter. -----------------------------------------
+# Get baseline first
+TOTAL_CLIENTS=$(curl -s "${H_AUTH[@]}" "$HOST/api/v0/clients" \
+	| jq '.clients | length')
+UP_CLIENTS=$(curl -s "${H_AUTH[@]}" "$HOST/api/v0/clients?filter=uploads" \
+	| jq '.clients | length')
+DOWN_CLIENTS=$(curl -s "${H_AUTH[@]}" "$HOST/api/v0/clients?filter=downloads" \
+	| jq '.clients | length')
+ACTIVE_CLIENTS=$(curl -s "${H_AUTH[@]}" "$HOST/api/v0/clients?filter=active" \
+	| jq '.clients | length')
+if [ "$UP_CLIENTS" -le "$TOTAL_CLIENTS" ] 2>/dev/null \
+   && [ "$DOWN_CLIENTS" -le "$TOTAL_CLIENTS" ] 2>/dev/null \
+   && [ "$ACTIVE_CLIENTS" -le "$TOTAL_CLIENTS" ] 2>/dev/null; then
+	_pass "/clients filters: total=$TOTAL_CLIENTS up=$UP_CLIENTS down=$DOWN_CLIENTS active=$ACTIVE_CLIENTS (each ≤ total)"
+else
+	_fail "clients filter sizing" \
+		"total=$TOTAL_CLIENTS up=$UP_CLIENTS down=$DOWN_CLIENTS active=$ACTIVE_CLIENTS"
+fi
+# `active` = |uploads ∪ downloads|, so it sits in
+# [max(up, down), up+down]. The lower bound holds because every
+# uploads-or-downloads-only peer is in active; the upper bound holds
+# because a peer simultaneously in both states (upload_state=uploading
+# AND download_state=downloading) gets counted once in active but
+# twice in (up + down). Exact equality is intentionally not asserted
+# because the intersection count is unobservable from filter results
+# alone.
+EXP_UPPER=$((UP_CLIENTS + DOWN_CLIENTS))
+if [ "$ACTIVE_CLIENTS" -ge "$UP_CLIENTS" ] 2>/dev/null \
+   && [ "$ACTIVE_CLIENTS" -ge "$DOWN_CLIENTS" ] 2>/dev/null \
+   && [ "$ACTIVE_CLIENTS" -le "$EXP_UPPER" ] 2>/dev/null; then
+	_pass "/clients?filter=active sits in [max(up,down), up+down]"
+else
+	_fail "clients active span" \
+		"active=$ACTIVE_CLIENTS up=$UP_CLIENTS down=$DOWN_CLIENTS (expected max..sum)"
+fi
+# Verify every entry in /clients?filter=uploads truly has upload_state=uploading
+BAD=$(curl -s "${H_AUTH[@]}" "$HOST/api/v0/clients?filter=uploads" \
+	| jq -r '.clients[] | select(.upload_state != "uploading") | .client_ecid' \
+	| head -1)
+if [ -z "$BAD" ]; then
+	_pass "/clients?filter=uploads only returns upload_state=uploading peers"
+else
+	_fail "clients uploads filter content" \
+		"client_ecid $BAD has wrong upload_state"
+fi
+# Bogus filter → 400
+RC=$(curl -s -o /dev/null -w "%{http_code}" "${H_AUTH[@]}" \
+	"$HOST/api/v0/clients?filter=alphabetical")
+if [ "$RC" = "400" ]; then
+	_pass "/clients?filter=<bogus> → 400"
+else
+	_fail "clients bogus filter" "expected 400, got $RC"
+fi
+
+# --- 10. /events ?channels= filter. ------------------------------
+# Test 8 left the daemon disconnected; reconnect so download_* /
+# status_* events have a reason to fire.
+curl -s -X POST "${H_AUTH[@]}" "$HOST/api/v0/networks/connect" > /dev/null
+sleep 6
+curl -s -X DELETE "${H_AUTH[@]}" "$HOST/api/v0/downloads/$TEST_HASH" > /dev/null
+_wait_for_no_download || true
+: > "$SSE"
+( curl -s -m 10 -N "${H_AUTH[@]}" \
+	"$HOST/api/v0/events?channels=downloads,status" \
+	>> "$SSE" 2>&1 ) &
+PID=$!
+sleep 2
+curl -s -X POST "${H_AUTH[@]}" -H "Content-Type: application/json" \
+	-d "{\"ed2k_link\":\"$TEST_LINK\"}" "$HOST/api/v0/downloads" > /dev/null
+sleep 6
+kill $PID 2>/dev/null
+wait $PID 2>/dev/null
+
+# In the channels=downloads,status window we MUST see download_* / status_*
+# events and MUST NOT see client_* / server_* / shared_* / log_* events.
+if grep -qE "^event: (download_added|download_updated|status_changed)$" "$SSE"; then
+	_pass "/events?channels=downloads,status delivers download/status events"
+else
+	_fail "events channel-filter positive" \
+		"no download/status events seen; sample: $(head -10 "$SSE")"
+fi
+LEAKED=$(grep -cE "^event: (client_|server_|shared_|log_|search_)" "$SSE" || true)
+if [ "$LEAKED" -eq 0 ]; then
+	_pass "/events?channels=downloads,status excludes client/server/shared/log/search events"
+else
+	_fail "events channel-filter leak" \
+		"$LEAKED off-channel events leaked through"
+fi
+
+# Positive: ?channels=search delivers search events and excludes downloads.
+: > "$SSE"
+( curl -s -m 12 -N "${H_AUTH[@]}" \
+	"$HOST/api/v0/events?channels=search" \
+	>> "$SSE" 2>&1 ) &
+PID=$!
+sleep 1
+curl -s -X POST "${H_AUTH[@]}" -H "Content-Type: application/json" \
+	-d '{"query":"ubuntu","type":"local"}' "$HOST/api/v0/search" > /dev/null
+sleep 8
+kill $PID 2>/dev/null
+wait $PID 2>/dev/null
+
+if grep -qE "^event: search_progress$" "$SSE"; then
+	_pass "/events?channels=search delivers search_progress"
+else
+	_fail "events channel=search positive" \
+		"no search_progress in 8 s; sample: $(head -10 "$SSE")"
+fi
+LEAKED=$(grep -cE "^event: (download_|status_|client_|server_|shared_|log_)" "$SSE" || true)
+if [ "$LEAKED" -eq 0 ]; then
+	_pass "/events?channels=search excludes non-search events"
+else
+	_fail "events channel=search leak" \
+		"$LEAKED off-channel events leaked through"
+fi
+
+# --- Summary. -----------------------------------------------------
+echo
+if [ "$FAIL_COUNT" -eq 0 ]; then
+	echo "OK: $TEST_COUNT/$TEST_COUNT passed"
+	exit 0
+fi
+echo "FAIL: $FAIL_COUNT/$TEST_COUNT failed"
+exit 1
diff --git a/unittests/curl-tests/amuleapi/27-static-frontend.sh b/unittests/curl-tests/amuleapi/27-static-frontend.sh
new file mode 100755
index 0000000000..84a927e48d
--- /dev/null
+++ b/unittests/curl-tests/amuleapi/27-static-frontend.sh
@@ -0,0 +1,178 @@
+#!/usr/bin/env bash
+#
+# amuleapi 27-static-frontend — static-frontend fallthrough.
+#
+# Asserts that GET / HEAD requests outside `/api/` are served from the
+# directory pointed to by `[Server]/StaticRoot` when set; that the
+# realpath-based symlink containment rejects escapes; that the 16 MiB
+# size cap fires; that conditional GET via `If-None-Match` short-
+# circuits to 304; and that the SPA fallback to `index.html` only
+# kicks in for extension-less misses (not for missing assets).
+#
+# Requires `[Server]/StaticRoot` set to a writable directory containing
+# an `index.html` (the script plants symlinks + a 17 MiB sentinel there
+# during the run). `run-all.sh` provisions /tmp/amuleapi-27-static-frontend-static
+# automatically; manual runs need to edit the conf themselves.
+# Note: discovery of the install-path default (`AMULEAPI_STATIC_DIR`,
+# bundle Resources, wxStandardPaths) is covered by StaticFsTest at the
+# unit level; this script covers the static-serve wire mechanics.
+#
+# Usage:
+#   amuleapi --config-dir=/tmp/amuleapi-regtest &
+#   ./27-static-frontend.sh
+#
+# Exits 0 on success, 1 on any failed assertion, 2 on bring-up error.
+
+set -u
+set -o pipefail
+
+HOST=${HOST:-localhost:4713}
+ADMIN_PASS=${ADMIN_PASS:-adminpass}
+
+FAIL_COUNT=0
+TEST_COUNT=0
+
+CURL_BODY_FILE=$(mktemp -t amuleapi_27_static_frontend_body.XXXXXX)
+CURL_HEAD_FILE=$(mktemp -t amuleapi_27_static_frontend_head.XXXXXX)
+trap 'rm -f "$CURL_BODY_FILE" "$CURL_HEAD_FILE"' EXIT
+
+_die()  { echo "FATAL: $*" >&2; exit 2; }
+_pass() { TEST_COUNT=$((TEST_COUNT+1)); echo "  PASS  $1"; }
+_fail() {
+	TEST_COUNT=$((TEST_COUNT+1)); FAIL_COUNT=$((FAIL_COUNT+1))
+	echo "  FAIL  $1"
+	shift
+	for arg in "$@"; do echo "        $arg"; done
+}
+
+_curl() {
+	local resp
+	resp=$(curl -s --max-time 10 \
+		-D "$CURL_HEAD_FILE" \
+		-o "$CURL_BODY_FILE" -w '%{http_code}' "$@") \
+		|| _die "curl invocation failed for $*"
+	CURL_STATUS=$resp
+	CURL_BODY=$(cat "$CURL_BODY_FILE")
+	CURL_HEAD=$(cat "$CURL_HEAD_FILE")
+}
+
+_assert_status() {
+	local expected=$1 label=$2
+	if [ "$CURL_STATUS" = "$expected" ]; then
+		_pass "$label (HTTP $CURL_STATUS)"
+	else
+		_fail "$label" "expected HTTP $expected, got $CURL_STATUS" \
+			"body head: $(printf '%s' "$CURL_BODY" | head -c 200)"
+	fi
+}
+
+if ! command -v jq >/dev/null 2>&1; then
+	_die "jq is required for JSON assertions. brew install jq."
+fi
+if ! curl -s -o /dev/null --max-time 2 "$HOST/api/v0/version" 2>/dev/null; then
+	_die "amuleapi at $HOST is not reachable. Start amuleapi first."
+fi
+
+# Resolve the configured StaticRoot from the daemon's conf so the
+# script can plant a symlink + oversized file in it during the run.
+# run-all.sh provisions a writable /tmp scratch dir before each
+# 27-static-frontend run; for manual runs, set StaticRoot in amuleapi.conf to a
+# writable directory containing an index.html before launching the
+# daemon. (Discovery of the install-path default is unit-tested in
+# StaticFsTest and manually verified per-platform — this phase is
+# specifically the static-serve mechanics, not the discovery chain.)
+CONF_DIR=${AMULEAPI_CONFIG_DIR:-/tmp/amuleapi-regtest}
+STATIC_ROOT=$(awk -F= '/^StaticRoot=/ {sub(/[\r ]+$/,"",$2); print $2; exit}' \
+	"$CONF_DIR/amuleapi.conf" 2>/dev/null)
+
+if [ -z "$STATIC_ROOT" ]; then
+	_die "[Server]/StaticRoot is empty in $CONF_DIR/amuleapi.conf — set it to a writable dir with an index.html, then re-run."
+fi
+
+if [ ! -d "$STATIC_ROOT" ]; then
+	_die "StaticRoot=$STATIC_ROOT in conf does not exist on disk"
+fi
+if [ ! -w "$STATIC_ROOT" ]; then
+	_die "StaticRoot=$STATIC_ROOT is not writable (27-static-frontend plants symlinks + an oversized file there)"
+fi
+
+echo "amuleapi 27-static-frontend @ $HOST — StaticRoot=$STATIC_ROOT"
+
+# Stage transient assets in StaticRoot for the duration of the run.
+# Restore the directory's pre-test state on exit so re-running doesn't
+# accumulate stale symlinks.
+trap 'rm -f "$CURL_BODY_FILE" "$CURL_HEAD_FILE" \
+	"$STATIC_ROOT/escape.txt" "$STATIC_ROOT/escape.css" \
+	"$STATIC_ROOT/huge.bin"' EXIT
+
+# --- 1. GET / serves the placeholder index. -----------------------
+_curl "$HOST/"
+_assert_status 200 "GET / serves the placeholder index"
+case "$CURL_HEAD" in
+	*[Cc]ontent-[Tt]ype:*text/html*) _pass "Content-Type is text/html on /" ;;
+	*) _fail "/ Content-Type" "expected text/html, got: $(echo "$CURL_HEAD" | grep -i content-type)" ;;
+esac
+
+# --- 2. Strong ETag header is present. ----------------------------
+ETAG=$(echo "$CURL_HEAD" | awk -F': ' 'tolower($1) == "etag" {gsub(/\r/,""); print $2}')
+if [ -n "$ETAG" ]; then
+	_pass "GET / emits an ETag header ($ETAG)"
+else
+	_fail "/ ETag" "no ETag header found in response headers"
+fi
+
+# --- 3. If-None-Match → 304. --------------------------------------
+_curl -H "If-None-Match: $ETAG" "$HOST/"
+_assert_status 304 "If-None-Match matching ETag → 304"
+
+# --- 4. /index.html explicit also works. --------------------------
+_curl "$HOST/index.html"
+_assert_status 200 "GET /index.html → 200"
+
+# --- 5. SPA fallback for extension-less unknown route. ------------
+_curl "$HOST/transfers"
+_assert_status 200 "GET /transfers (extension-less unknown) → 200 SPA fallback"
+
+# --- 6. Missing-with-extension is an honest 404. ------------------
+_curl "$HOST/missing.css"
+_assert_status 404 "GET /missing.css → 404"
+
+# --- 7. /api/v0/* still routes through the API dispatcher. --------
+_curl "$HOST/api/v0/version"
+_assert_status 200 "GET /api/v0/version is still routed to API (200)"
+
+# --- 8. Symlink-escape containment (extension-bearing). -----------
+# `realpath` resolves through the symlink. If the result escapes
+# StaticRoot, the daemon must 404. Anything else is a leak.
+ln -sf /etc/passwd "$STATIC_ROOT/escape.txt"
+_curl "$HOST/escape.txt"
+_assert_status 404 "Symlink /escape.txt → /etc/passwd is rejected (404)"
+case "$CURL_BODY" in
+	*root:*) _fail "escape.txt body" "response leaked /etc/passwd contents" ;;
+	*) _pass "/escape.txt response does not leak /etc/passwd" ;;
+esac
+
+ln -sf /etc/passwd "$STATIC_ROOT/escape.css"
+_curl "$HOST/escape.css"
+_assert_status 404 "Symlink /escape.css → /etc/passwd is rejected (404)"
+
+# --- 9. 16 MiB size cap. ------------------------------------------
+# Plant a 17 MiB regular file inside StaticRoot. The daemon should
+# stat it, see it exceeds the cap, and 404 without reading.
+if command -v mkfile >/dev/null 2>&1; then
+	mkfile -n 17m "$STATIC_ROOT/huge.bin" >/dev/null
+else
+	dd if=/dev/zero of="$STATIC_ROOT/huge.bin" bs=1m count=17 \
+		status=none 2>/dev/null
+fi
+_curl "$HOST/huge.bin"
+_assert_status 404 "Oversized /huge.bin (>16 MiB) → 404"
+
+# --- Summary. -----------------------------------------------------
+echo
+if [ "$FAIL_COUNT" -eq 0 ]; then
+	echo "OK: $TEST_COUNT/$TEST_COUNT passed"
+	exit 0
+fi
+echo "FAIL: $FAIL_COUNT/$TEST_COUNT failed"
+exit 1
diff --git a/unittests/curl-tests/amuleapi/run-all.sh b/unittests/curl-tests/amuleapi/run-all.sh
new file mode 100755
index 0000000000..3e0f16081a
--- /dev/null
+++ b/unittests/curl-tests/amuleapi/run-all.sh
@@ -0,0 +1,188 @@
+#!/usr/bin/env bash
+#
+# Orchestrator for the amuleapi curl-smoke matrix.
+#
+# Brings up a fresh amuleapi daemon for each script, runs the
+# script, and aggregates pass/fail. The fresh-daemon-per-script
+# pattern isolates state — most importantly, 02-auth.sh fires the
+# rate-limit lockout (5 failed logins → 300 s IP lockout) which would
+# block every subsequent script's /auth/login. Restarting wipes the
+# in-memory CRateLimiter buckets.
+#
+# Setup per phase:
+#   1. pkill any running amuleapi
+#   2. wipe + recreate /tmp/amuleapi-regtest config dir
+#   3. set admin pass (one-shot CLI invocation, daemon exits)
+#   4. set guest pass (second one-shot — App.cpp's set-pass paths are
+#      mutually exclusive, so admin and guest need separate runs)
+#   5. start the daemon in foreground, log to /tmp/amuleapi.log
+#   6. sleep 5 s for the refresher to populate its caches (first
+#      GET_UPDATE tick is the heaviest — sends every alive ECID with
+#      full identity)
+#   7. run the phase script
+#
+# Usage:
+#   ./run-all.sh                                                 # run every script in
+#                                                                # the canonical order
+#   ./run-all.sh 12-downloads-add-patch.sh 13-downloads-delete-clear.sh  # run a subset
+
+set -u
+
+# Resolve our location so the orchestrator runs from any cwd.
+SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd)
+
+# Locate the repo root by climbing out of unittests/curl-tests/amuleapi/.
+# AMULEAPI_ROOT remains an env override for unusual layouts; the default
+# follows the script's own location so anyone who checks the repo out
+# elsewhere works without editing this file.
+ROOT="${AMULEAPI_ROOT:-$(cd "$SCRIPT_DIR/../../.." && pwd)}"
+BIN="${AMULEAPI_BIN:-$ROOT/build-macos/src/webapi/amuleapi}"
+
+if [ ! -x "$BIN" ]; then
+	echo "FATAL: amuleapi binary not found at $BIN" >&2
+	echo "       set AMULEAPI_BIN env var to point at it." >&2
+	exit 2
+fi
+
+run_phase() {
+	local script=$1
+	echo "==================== $script ===================="
+	# Narrowly target the regtest daemon so a dev who happens to have
+	# `vim path/to/amuleapi.cpp` open doesn't get their editor killed.
+	# The config-dir suffix is uniquely ours.
+	pkill -f "amuleapi --config-dir=/tmp/amuleapi-regtest" 2>/dev/null
+	sleep 1
+	rm -rf /tmp/amuleapi-regtest
+	mkdir -p /tmp/amuleapi-regtest
+	"$BIN" --config-dir=/tmp/amuleapi-regtest \
+		--host=127.0.0.1 --port=4712 --password=amule \
+		--set-admin-pass=adminpass > /dev/null 2>&1
+	"$BIN" --config-dir=/tmp/amuleapi-regtest \
+		--host=127.0.0.1 --port=4712 --password=amule \
+		--set-guest-pass=guestpass > /dev/null 2>&1
+	# 27-static-frontend exercises the static-frontend serve path. It
+	# plants symlinks + an oversized file into StaticRoot during the
+	# run, so the dir has to be writable. The bundled source tree is
+	# read-only in container CI; copy the placeholder out to a /tmp
+	# scratch dir and point StaticRoot at the copy. Other scripts
+	# leave it empty so the install-path discovery chain stays
+	# exercised by 27-static-frontend only.
+	if [ "$script" = "27-static-frontend.sh" ]; then
+		STATIC_SRC="$ROOT/src/webapi/static"
+		STATIC_DIR=/tmp/amuleapi-static-frontend
+		rm -rf "$STATIC_DIR"
+		mkdir -p "$STATIC_DIR"
+		if [ -d "$STATIC_SRC" ]; then
+			cp -R "$STATIC_SRC"/. "$STATIC_DIR/"
+		fi
+		sed -i'.bak' \
+			"s|^StaticRoot=.*|StaticRoot=$STATIC_DIR|" \
+			/tmp/amuleapi-regtest/amuleapi.conf
+		rm -f /tmp/amuleapi-regtest/amuleapi.conf.bak
+	fi
+	"$BIN" --config-dir=/tmp/amuleapi-regtest \
+		--host=127.0.0.1 --port=4712 --password=amule \
+		> /tmp/amuleapi.log 2>&1 &
+	# Poll /version until the daemon is ready instead of guessing the
+	# cold-start time. The first EC GET_UPDATE roundtrip can take a
+	# couple of seconds on a slow CI runner, and the cap of 12 leaves
+	# headroom while still failing fast on a genuine bring-up bug.
+	local i
+	for i in 1 2 3 4 5 6 7 8 9 10 11 12; do
+		if curl -s -o /dev/null --max-time 1 \
+		    http://localhost:4713/api/v0/version 2>/dev/null; then
+			break
+		fi
+		sleep 0.5
+	done
+	# Scripts that bounce the daemon themselves (25-cors.sh rewrites
+	# amuleapi.conf to flip CORS modes) read these envs to know how
+	# to restart cleanly.
+	AMULEAPI_BIN="$BIN" \
+	AMULEAPI_CONFIG_DIR=/tmp/amuleapi-regtest \
+	AMULEAPI_LOG=/tmp/amuleapi.log \
+	bash "$SCRIPT_DIR/$script"
+	local rc=$?
+	echo "$script exit=$rc"
+	# If a script failed AND the daemon is currently rate-limiting,
+	# the operator likely hit the 02-auth fallout: 7 deliberate
+	# wrong-password attempts armed a 5-minute IP lockout that later
+	# scripts inherit when the orchestrator's daemon restart isn't
+	# enough to clear the in-memory bucket. Print a one-line tip so
+	# the operator doesn't lose half an hour chasing the wrong layer.
+	if [ "$rc" -ne 0 ]; then
+		local probe=$(curl -s -X POST -H "Content-Type: application/json" \
+			-o /dev/null -w "%{http_code}" \
+			-d "{\"password\":\"adminpass\"}" \
+			http://localhost:4713/api/v0/auth/login 2>/dev/null)
+		if [ "$probe" = "429" ]; then
+			echo "TIP: amuleapi is currently rate-limiting login (HTTP 429)." \
+			     "If you ran 02-auth.sh right before this, that's the 7-bad-pass" \
+			     "arm carried over. Restart amuleapi (kills the bucket)" \
+			     "before re-running."
+		fi
+	fi
+	return $rc
+}
+
+# Canonical execution order. Numeric prefix doubles as dependency
+# ordering: auth before any mutation, refresher-consolidation tests
+# before later read tests that rely on the consolidated tick shape,
+# CORS / static-frontend after the API surface tests so failures in
+# the new transports don't mask earlier regressions.
+PHASES=(
+	01-version-and-errors.sh
+	02-auth.sh
+	03-read-status.sh
+	04-read-downloads-shared.sh
+	05-read-servers-kad-categories-prefs.sh
+	06-read-logs.sh
+	07-read-stats-and-search-results.sh
+	08-read-download-parts.sh
+	09-refresher-consolidation.sh
+	10-refresher-lazy-ondemand.sh
+	11-downloads-default-filter.sh
+	12-downloads-add-patch.sh
+	13-downloads-delete-clear.sh
+	14-servers-mutations.sh
+	15-preferences-patch.sh
+	16-networks-connect.sh
+	17-shared-priority-patch.sh
+	18-categories-crud.sh
+	19-search.sh
+	20-etag-conditional-get.sh
+	21-sse-heartbeat.sh
+	22-sse-diff-emission.sh
+	23-sse-replay.sh
+	24-sse-resync.sh
+	25-cors.sh
+	26-rfc-followup-endpoints.sh
+	27-static-frontend.sh
+)
+
+# Override list from the command line if given.
+if [ "$#" -gt 0 ]; then
+	PHASES=("$@")
+fi
+
+OVERALL=0
+for s in "${PHASES[@]}"; do
+	if [ ! -f "$SCRIPT_DIR/$s" ]; then
+		echo "skip $s (not present in $SCRIPT_DIR)"
+		continue
+	fi
+	if ! run_phase "$s"; then
+		OVERALL=1
+	fi
+done
+
+# Final teardown — same narrow scope as the per-phase kill at line 53
+# so an editor with `vim path/to/amuleapi.cpp` open survives the run.
+pkill -f "amuleapi --config-dir=/tmp/amuleapi-regtest" 2>/dev/null
+echo
+if [ "$OVERALL" -eq 0 ]; then
+	echo "OVERALL: ALL PHASES PASSED"
+else
+	echo "OVERALL: ONE OR MORE PHASES FAILED"
+fi
+exit "$OVERALL"
diff --git a/unittests/curl-tests/amuleweb-smoke/phase0.sh b/unittests/curl-tests/amuleweb-smoke/phase0.sh
new file mode 100755
index 0000000000..e44f6bd430
--- /dev/null
+++ b/unittests/curl-tests/amuleweb-smoke/phase0.sh
@@ -0,0 +1,130 @@
+#!/usr/bin/env bash
+#
+# Amuleweb smoke test — runs against a stock amuleweb (PHP frontend on
+# port 4711, default template) and checks the four pages that exercise
+# the legacy path. This branch (the amuleapi work) explicitly does NOT
+# touch amuleweb's source; this script's job is to catch any
+# unintended cross-cut — e.g. someone misconfigures the CMake graph
+# such that the legacy binary changes behaviour, or a libwebcommon
+# header bleeds an include into a PHP TU.
+#
+# Usage:
+#   amuleweb --no-php-checks &     # start amuleweb on :4711
+#   ./phase0.sh                    # asserts the four landing pages
+#
+# Environment:
+#   HOST=localhost:4711       amuleweb endpoint
+#   PASS=x                    amuleweb full-access password (matches
+#                             amuleweb's `--admin-pass` / remote.conf)
+#
+# Exits 0 on success, 1 on any failed assertion, 2 on bring-up error.
+
+set -u
+set -o pipefail
+
+HOST=${HOST:-localhost:4711}
+PASS=${PASS:-x}
+
+FAIL_COUNT=0
+TEST_COUNT=0
+
+CURL_BODY_FILE=$(mktemp -t amuleweb_smoke_body.XXXXXX)
+CURL_HEADERS_FILE=$(mktemp -t amuleweb_smoke_headers.XXXXXX)
+COOKIE_JAR=$(mktemp -t amuleweb_smoke_cookies.XXXXXX)
+trap 'rm -f "$CURL_BODY_FILE" "$CURL_HEADERS_FILE" "$COOKIE_JAR"' EXIT
+
+_die()  { echo "FATAL: $*" >&2; exit 2; }
+_pass() { TEST_COUNT=$((TEST_COUNT+1)); echo "  PASS  $1"; }
+_fail() {
+	TEST_COUNT=$((TEST_COUNT+1)); FAIL_COUNT=$((FAIL_COUNT+1))
+	echo "  FAIL  $1"
+	shift
+	for arg in "$@"; do echo "        $arg"; done
+}
+
+_curl() {
+	local resp
+	resp=$(curl -s --compressed --max-time 10 \
+		-b "$COOKIE_JAR" -c "$COOKIE_JAR" \
+		-o "$CURL_BODY_FILE" -w '%{http_code}' "$@") \
+		|| _die "curl invocation failed for $*"
+	CURL_STATUS=$resp
+	CURL_BODY=$(cat "$CURL_BODY_FILE")
+}
+
+_assert_status() {
+	local expected=$1 label=$2
+	if [ "$CURL_STATUS" = "$expected" ]; then
+		_pass "$label (HTTP $CURL_STATUS)"
+	else
+		_fail "$label" "expected HTTP $expected, got $CURL_STATUS" \
+			"body head: $(printf '%s' "$CURL_BODY" | head -c 200)"
+	fi
+}
+
+_assert_body_contains() {
+	local needle=$1 label=$2
+	if printf '%s' "$CURL_BODY" | grep -q -- "$needle"; then
+		_pass "$label"
+	else
+		_fail "$label" "needle '$needle' not found" \
+			"body head: $(printf '%s' "$CURL_BODY" | head -c 200)"
+	fi
+}
+
+# Preflight: amuleweb up?
+if ! curl -s -o /dev/null --max-time 2 "$HOST/" 2>/dev/null; then
+	_die "amuleweb at $HOST is not reachable. Start amuled + amuleweb first."
+fi
+
+echo "amuleweb smoke @ $HOST"
+
+# 1. /login.php — the unauthenticated landing page. The PHP template
+#    renders the login form; we just need a 200 + a hint that the form
+#    rendered. amuleweb's default template emits the `<input type="password"
+#    name="pass"` element, which is what the user actually types into.
+_curl "$HOST/login.php"
+_assert_status 200 "GET /login.php returns 200"
+_assert_body_contains 'name="pass"' "/login.php renders password input"
+
+# 2. /amuleweb-main-dload.php (downloads list) before login → must
+#    redirect / 401 / serve the login page. amuleweb's default template
+#    redirects to /login.php on missing session, which curl follows
+#    with -L; without -L we get a 302. Either is acceptable for the
+#    smoke check; we just want NOT 5xx.
+_curl "$HOST/amuleweb-main-dload.php"
+case "$CURL_STATUS" in
+	200|302|401) _pass "GET /amuleweb-main-dload.php pre-login (HTTP $CURL_STATUS)" ;;
+	*)           _fail "GET /amuleweb-main-dload.php pre-login" \
+	                 "unexpected status $CURL_STATUS" ;;
+esac
+
+# 3. POST /login.php with the configured password → 200 + sets a
+#    PHP session cookie. amuleweb's session cookie name is `amuleweb_*`.
+_curl -X POST -d "pass=$PASS" "$HOST/login.php"
+_assert_status 200 "POST /login.php with admin password"
+if grep -q '^amuleweb_' "$COOKIE_JAR" 2>/dev/null \
+   || grep -qi 'session' "$COOKIE_JAR" 2>/dev/null; then
+	_pass "POST /login.php sets a session cookie"
+else
+	_fail "POST /login.php sets a session cookie" \
+		"no session cookie found in jar" \
+		"jar: $(cat "$COOKIE_JAR" 2>/dev/null | head -c 400)"
+fi
+
+# 4. /amuleweb-main-dload.php after login → 200 + table markup. The
+#    default template emits a `<table` for the download list. If
+#    amuleweb's PHP path is broken (the carve-out scenario this script
+#    guards against), this is where it shows up.
+_curl "$HOST/amuleweb-main-dload.php"
+_assert_status 200 "GET /amuleweb-main-dload.php post-login"
+_assert_body_contains '<table' "/amuleweb-main-dload.php renders a table"
+
+# Summary.
+echo
+if [ "$FAIL_COUNT" -eq 0 ]; then
+	echo "OK: $TEST_COUNT/$TEST_COUNT passed"
+	exit 0
+fi
+echo "FAIL: $FAIL_COUNT/$TEST_COUNT failed"
+exit 1
diff --git a/unittests/tests/AmuleApiConfigTest.cpp b/unittests/tests/AmuleApiConfigTest.cpp
new file mode 100644
index 0000000000..0950d1eb2d
--- /dev/null
+++ b/unittests/tests/AmuleApiConfigTest.cpp
@@ -0,0 +1,241 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#include <muleunit/test.h>
+
+#include "AmuleApiConfig.h"
+
+#include <wx/file.h>
+#include <wx/filename.h>
+#include <wx/stdpaths.h>
+#include <wx/utils.h>
+
+#include <cstdlib>
+#include <cstring>
+#include <string>
+#include <vector>
+
+#ifndef _WIN32
+#  include <sys/stat.h>
+#  include <unistd.h>
+#endif
+
+
+using namespace muleunit;
+
+
+DECLARE(AmuleApiConfig)
+	// Fresh per-test config dir under the system temp tree. Tearing
+	// down inside the test bodies avoids muleunit's lack of a
+	// TearDown hook in the DECLARE_SIMPLE style — each test owns its
+	// own dir. wxStandardPaths::GetTempDir() returns `/tmp` on
+	// POSIX and `%TEMP%` on Windows (typically `C:\\Users\\<user>\\
+	// AppData\\Local\\Temp`), so the test is portable across the CI
+	// matrix.
+	wxString MakeTmpDir(const char *tag)
+	{
+		wxString d;
+		d.Printf("%s/amuleapi-cfg-test-%s-%ld",
+			wxStandardPaths::Get().GetTempDir(),
+			tag, static_cast<long>(::wxGetProcessId()));
+		// Best-effort cleanup of any stragglers from a prior crashed run.
+		wxString secret = d + "/amuleapi-jwt-secret";
+		wxString pwfile = d + "/amuleapi-passwords";
+		wxString conf   = d + "/amuleapi.conf";
+		::wxRemoveFile(secret);
+		::wxRemoveFile(pwfile);
+		::wxRemoveFile(conf);
+		::wxRmdir(d);
+		return d;
+	}
+END_DECLARE;
+
+
+TEST(AmuleApiConfig, DefaultConfigDirIsNonEmpty)
+{
+	const wxString d = DefaultConfigDir();
+	ASSERT_TRUE(!d.IsEmpty());
+}
+
+
+TEST(AmuleApiConfig, FreshLoadCreatesAllThreeFiles)
+{
+	const wxString dir = MakeTmpDir("fresh");
+	CAmuleApiConfig cfg;
+	ASSERT_TRUE(cfg.Load(dir));
+
+	ASSERT_TRUE(::wxFileExists(dir + "/amuleapi.conf"));
+	ASSERT_TRUE(::wxFileExists(dir + "/amuleapi-jwt-secret"));
+	ASSERT_TRUE(::wxFileExists(dir + "/amuleapi-passwords"));
+}
+
+
+TEST(AmuleApiConfig, FreshLoadProducesStreamingDefaults)
+{
+	const wxString dir = MakeTmpDir("stream-defaults");
+	CAmuleApiConfig cfg;
+	ASSERT_TRUE(cfg.Load(dir));
+	ASSERT_EQUALS(static_cast<unsigned>(16384),
+		cfg.StreamingCfg().event_bus_ring_capacity);
+}
+
+
+TEST(AmuleApiConfig, GeneratedJwtSecretIs32Bytes)
+{
+	const wxString dir = MakeTmpDir("jwt32");
+	CAmuleApiConfig cfg;
+	ASSERT_TRUE(cfg.Load(dir));
+	ASSERT_EQUALS(static_cast<size_t>(32), cfg.JwtSecret().size());
+}
+
+
+TEST(AmuleApiConfig, GeneratedJwtSecretIsRandom)
+{
+	const wxString dir_a = MakeTmpDir("jwt-a");
+	CAmuleApiConfig cfg_a;
+	ASSERT_TRUE(cfg_a.Load(dir_a));
+	const std::vector<unsigned char> a = cfg_a.JwtSecret();
+
+	const wxString dir_b = MakeTmpDir("jwt-b");
+	CAmuleApiConfig cfg_b;
+	ASSERT_TRUE(cfg_b.Load(dir_b));
+	const std::vector<unsigned char> b = cfg_b.JwtSecret();
+
+	// Two fresh dirs → two distinct secrets. ~2^256 collision odds.
+	ASSERT_TRUE(a != b);
+}
+
+
+TEST(AmuleApiConfig, JwtSecretRoundTripStable)
+{
+	const wxString dir = MakeTmpDir("jwt-rt");
+
+	CAmuleApiConfig cfg1;
+	ASSERT_TRUE(cfg1.Load(dir));
+	const std::vector<unsigned char> first = cfg1.JwtSecret();
+
+	CAmuleApiConfig cfg2;
+	ASSERT_TRUE(cfg2.Load(dir));
+	const std::vector<unsigned char> second = cfg2.JwtSecret();
+
+	// Second load reads what the first generated — same bytes.
+	ASSERT_TRUE(first == second);
+}
+
+
+TEST(AmuleApiConfig, EmptyPasswordsFilePassesLoad)
+{
+	const wxString dir = MakeTmpDir("pw-empty");
+	CAmuleApiConfig cfg;
+	ASSERT_TRUE(cfg.Load(dir));
+	// Default state: both roles disabled until --set-*-pass writes a line.
+	ASSERT_TRUE(cfg.AdminPasswordMd5().empty());
+	ASSERT_TRUE(cfg.GuestPasswordMd5().empty());
+}
+
+
+TEST(AmuleApiConfig, WritePasswordsFileReloadable)
+{
+	const wxString dir = MakeTmpDir("pw-rt");
+	CAmuleApiConfig cfg;
+	ASSERT_TRUE(cfg.Load(dir));
+
+	// 32 lowercase hex chars; doesn't need to be a real MD5.
+	const std::string admin_md5 = "0123456789abcdef0123456789abcdef";
+	const std::string guest_md5 = "fedcba9876543210fedcba9876543210";
+	ASSERT_TRUE(cfg.WritePasswordsFile(dir, admin_md5, guest_md5));
+
+	CAmuleApiConfig cfg2;
+	ASSERT_TRUE(cfg2.Load(dir));
+	ASSERT_EQUALS(admin_md5, cfg2.AdminPasswordMd5());
+	ASSERT_EQUALS(guest_md5, cfg2.GuestPasswordMd5());
+}
+
+
+TEST(AmuleApiConfig, MalformedPasswordLineRejected)
+{
+	const wxString dir = MakeTmpDir("pw-bad");
+	// Hand-create the dir + a bad passwords file BEFORE Load() runs,
+	// otherwise the auto-create path writes a fresh empty file and
+	// we never exercise the parser failure path.
+	::wxMkdir(dir, 0700);
+	wxFile bad(dir + "/amuleapi-passwords", wxFile::write);
+	const char *bad_line = "admin=not_a_valid_md5\n";
+	bad.Write(bad_line, std::strlen(bad_line));
+	bad.Close();
+#ifndef _WIN32
+	::chmod(std::string((dir + "/amuleapi-passwords").utf8_str()).c_str(),
+		S_IRUSR | S_IWUSR);
+#endif
+
+	CAmuleApiConfig cfg;
+	ASSERT_FALSE(cfg.Load(dir));
+	ASSERT_TRUE(!cfg.LastError().empty());
+}
+
+
+#ifndef _WIN32
+// POSIX-only: the production hardening (mode-bit check in
+// AmuleApiConfig::EnforceOwnerOnly) is itself POSIX-only. Windows
+// uses ACLs rather than POSIX mode bits, and the typical Windows
+// daemon footprint (single-operator workstation, %USERPROFILE%-
+// scoped config dir) makes the threat model very different. If
+// amuleapi ever ships a Windows hardening pass (via GetSecurityInfo
+/// GetEffectiveRightsFromAcl on the secret file's DACL), the
+// matching test should land under `#ifdef _WIN32` here. Until then,
+// the #ifndef intentionally skips the assertion on Windows so the
+// test suite stays green there without misrepresenting the
+// platform's posture.
+TEST(AmuleApiConfig, LooserSecretFilePermissionsRejected)
+{
+	const wxString dir = MakeTmpDir("perm");
+	CAmuleApiConfig cfg;
+	ASSERT_TRUE(cfg.Load(dir));   // first load auto-creates with 0600
+
+	// Loosen the secret file to 0644 and verify the next Load fails
+	// with an actionable error. This guards the "operator
+	// accidentally chmodded the secret world-readable" scenario.
+	const std::string path =
+		std::string((dir + "/amuleapi-jwt-secret").utf8_str());
+	ASSERT_EQUALS(0, ::chmod(path.c_str(), S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH));
+
+	CAmuleApiConfig cfg2;
+	ASSERT_FALSE(cfg2.Load(dir));
+	ASSERT_TRUE(cfg2.LastError().find("0600") != std::string::npos);
+}
+#endif
+
+
+TEST(AmuleApiConfig, ConfDefaultsArePopulated)
+{
+	const wxString dir = MakeTmpDir("conf-defaults");
+	CAmuleApiConfig cfg;
+	ASSERT_TRUE(cfg.Load(dir));
+
+	ASSERT_EQUALS(std::string("127.0.0.1"), cfg.ServerCfg().bind_address);
+	ASSERT_EQUALS(static_cast<unsigned>(4713), cfg.ServerCfg().port);
+	ASSERT_EQUALS(std::string("127.0.0.1"), cfg.EcCfg().host);
+	ASSERT_EQUALS(static_cast<unsigned>(4712), cfg.EcCfg().port);
+	ASSERT_TRUE(!cfg.ServerCfg().allow_cors);
+}
diff --git a/unittests/tests/AuthTest.cpp b/unittests/tests/AuthTest.cpp
new file mode 100644
index 0000000000..133f3328a7
--- /dev/null
+++ b/unittests/tests/AuthTest.cpp
@@ -0,0 +1,309 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#include <muleunit/test.h>
+
+#include "Auth.h"
+
+#include "Jwt.h"
+
+#include <chrono>
+#include <ctime>
+#include <string>
+#include <thread>
+#include <vector>
+
+
+using namespace muleunit;
+using namespace webapi;
+
+
+DECLARE_SIMPLE(Auth)
+
+
+// ---------- CRevocationSet ---------------------------------------
+
+TEST(Auth, RevocationSet_FreshIsNotRevoked)
+{
+	CRevocationSet rs;
+	ASSERT_FALSE(rs.IsRevoked("never-seen-jti"));
+	ASSERT_EQUALS(static_cast<std::size_t>(0), rs.Size());
+}
+
+TEST(Auth, RevocationSet_RevokedJtiSticks)
+{
+	CRevocationSet rs;
+	const std::time_t hour_from_now = std::time(nullptr) + 3600;
+	rs.Revoke("abc-jti", hour_from_now);
+
+	ASSERT_TRUE(rs.IsRevoked("abc-jti"));
+	ASSERT_FALSE(rs.IsRevoked("def-jti"));
+	ASSERT_EQUALS(static_cast<std::size_t>(1), rs.Size());
+}
+
+TEST(Auth, RevocationSet_ExpiredEntryGcsOnNextLookup)
+{
+	CRevocationSet rs;
+	// Revoke with exp in the PAST — simulates a token whose JWT lifetime
+	// has already elapsed. IsRevoked must drop the entry rather than
+	// keep flagging it (no point — the JWT itself would fail Verify).
+	const std::time_t two_hours_ago = std::time(nullptr) - 7200;
+	rs.Revoke("stale-jti", two_hours_ago);
+
+	ASSERT_FALSE(rs.IsRevoked("stale-jti"));
+	ASSERT_EQUALS(static_cast<std::size_t>(0), rs.Size());
+}
+
+
+// ---------- CRateLimiter -----------------------------------------
+
+TEST(Auth, RateLimiter_NoFailuresMeansNoLockout)
+{
+	CRateLimiter::Config cfg;
+	cfg.window_seconds  = 60;
+	cfg.threshold       = 3;
+	cfg.lockout_seconds = 60;
+	CRateLimiter rl(cfg);
+	const auto d = rl.Check("192.0.2.1");
+	ASSERT_FALSE(d.locked_out);
+}
+
+TEST(Auth, RateLimiter_ThresholdFailuresLockOut)
+{
+	CRateLimiter::Config cfg;
+	cfg.window_seconds  = 60;
+	cfg.threshold       = 3;
+	cfg.lockout_seconds = 120;
+	CRateLimiter rl(cfg);
+	const std::string ip = "192.0.2.2";
+
+	rl.NoteFailure(ip);
+	ASSERT_FALSE(rl.Check(ip).locked_out);
+	rl.NoteFailure(ip);
+	ASSERT_FALSE(rl.Check(ip).locked_out);
+	rl.NoteFailure(ip);   // third → lockout armed
+	const auto d = rl.Check(ip);
+	ASSERT_TRUE(d.locked_out);
+	ASSERT_TRUE(d.retry_after_seconds > 0);
+	ASSERT_TRUE(d.retry_after_seconds <= 120);
+}
+
+TEST(Auth, RateLimiter_SuccessClearsBucket)
+{
+	CRateLimiter::Config cfg;
+	cfg.window_seconds  = 60;
+	cfg.threshold       = 2;
+	cfg.lockout_seconds = 60;
+	CRateLimiter rl(cfg);
+	const std::string ip = "192.0.2.3";
+
+	rl.NoteFailure(ip);
+	rl.NoteSuccess(ip);
+	rl.NoteFailure(ip);   // only one failure since the reset
+
+	ASSERT_FALSE(rl.Check(ip).locked_out);
+}
+
+TEST(Auth, RateLimiter_DifferentIpsTrackedSeparately)
+{
+	CRateLimiter::Config cfg;
+	cfg.window_seconds  = 60;
+	cfg.threshold       = 2;
+	cfg.lockout_seconds = 60;
+	CRateLimiter rl(cfg);
+
+	rl.NoteFailure("198.51.100.1");
+	rl.NoteFailure("198.51.100.1");   // locks out .1
+
+	ASSERT_TRUE (rl.Check("198.51.100.1").locked_out);
+	ASSERT_FALSE(rl.Check("198.51.100.2").locked_out);
+}
+
+
+TEST(Auth, RateLimiter_LockoutExpiresAfterLockoutSeconds)
+{
+	// Regression: forgetting the "lockout_until <= now → wipe
+	// bucket" path would silently jail the affected IP forever.
+	// Clock injection lets us step `now` past lockout_until without
+	// burning real time on a sleep.
+	CRateLimiter::Config cfg;
+	cfg.window_seconds  = 60;
+	cfg.threshold       = 1;
+	cfg.lockout_seconds = 1;
+	std::time_t fake_now = 1000;
+	CRateLimiter rl(cfg, [&] { return fake_now; });
+	const std::string ip = "203.0.113.7";
+
+	rl.NoteFailure(ip);
+	ASSERT_TRUE(rl.Check(ip).locked_out);
+
+	fake_now += 2;
+
+	const auto d = rl.Check(ip);
+	ASSERT_FALSE(d.locked_out);
+	ASSERT_EQUALS(static_cast<std::time_t>(0), d.retry_after_seconds);
+}
+
+
+TEST(Auth, RateLimiter_SlidingWindowSplitAttemptsStillLockOut)
+{
+	// Regression check for the original tumbling-window bug:
+	// threshold-1 failures in the tail of window N + threshold-1 in
+	// the head of window N+1 never tripped lockout because the old
+	// code reset failure_count whenever `now - window_start >
+	// window_seconds`. The current per-stamp eviction keeps any
+	// failure within `window_seconds` live in the count.
+	//
+	// Sequence (window=3, threshold=3) — clock-injected:
+	//   t=0  NoteFailure  → failures=[0],          count=1
+	//   t=3  NoteFailure  → failures=[0, 3],       count=2
+	//   t=4  NoteFailure  → failures=[3, 4],       count=2  (evict<1)
+	//   t=5  NoteFailure  → failures=[3, 4, 5],    count=3 → LOCKOUT
+	CRateLimiter::Config cfg;
+	cfg.window_seconds  = 3;
+	cfg.threshold       = 3;
+	cfg.lockout_seconds = 60;
+	std::time_t fake_now = 0;
+	CRateLimiter rl(cfg, [&] { return fake_now; });
+	const std::string ip = "203.0.113.9";
+
+	rl.NoteFailure(ip);                                          // t=0
+	fake_now = 3;
+	rl.NoteFailure(ip);                                          // t=3
+	fake_now = 4;
+	rl.NoteFailure(ip);                                          // t=4 (boundary crossing)
+	fake_now = 5;
+	rl.NoteFailure(ip);                                          // t=5 (sliding count reaches 3)
+	ASSERT_TRUE(rl.Check(ip).locked_out);
+}
+
+
+// ---------- Revocation × Verify cross-test -----------------------
+
+// Each side is unit-tested separately. This case wires the two
+// together: issue a token, mark its `jti` revoked, then verify
+// the token's body — Verify itself returns true (the token is
+// structurally valid and the MAC matches), but the caller must
+// consult CRevocationSet AFTER Verify and refuse if the jti is
+// listed. A regression where IsRevoked() short-circuits or where
+// Verify silently incorporates the revocation set would slip past
+// each component's own tests; this one would catch it.
+TEST(Auth, RevocationListBlocksOtherwiseValidToken)
+{
+	const std::vector<unsigned char> secret(32, 0xC1);
+	CJwt jwt(secret);
+	const CJwt::IssuedToken issued = jwt.Issue(Role::ADMIN);
+
+	CJwt::VerifyResult vr;
+	ASSERT_TRUE(jwt.Verify(issued.token, vr));
+	ASSERT_EQUALS(static_cast<int>(Role::ADMIN), static_cast<int>(vr.role));
+
+	CRevocationSet rev;
+	ASSERT_FALSE(rev.IsRevoked(vr.jti));
+
+	rev.Revoke(vr.jti, vr.exp);
+	ASSERT_TRUE(rev.IsRevoked(vr.jti));
+
+	// A second Verify of the same token still passes (cryptography
+	// is independent of the revocation list). The auth gate's
+	// contract is: Verify FIRST, then check IsRevoked, and refuse
+	// the request if either step rejects.
+	CJwt::VerifyResult vr2;
+	ASSERT_TRUE(jwt.Verify(issued.token, vr2));
+	ASSERT_EQUALS(vr.jti, vr2.jti);
+	ASSERT_TRUE(rev.IsRevoked(vr2.jti));
+}
+
+
+// ---------- Token extraction -------------------------------------
+
+TEST(Auth, ExtractBearerToken_HappyPath)
+{
+	const std::string token = ExtractBearerToken("Bearer abc.def.ghi");
+	ASSERT_EQUALS(std::string("abc.def.ghi"), token);
+}
+
+TEST(Auth, ExtractBearerToken_CaseInsensitiveScheme)
+{
+	ASSERT_EQUALS(std::string("xyz"), ExtractBearerToken("bearer xyz"));
+	ASSERT_EQUALS(std::string("xyz"), ExtractBearerToken("BEARER xyz"));
+}
+
+TEST(Auth, ExtractBearerToken_RejectsMissingValue)
+{
+	ASSERT_TRUE(ExtractBearerToken("Bearer ").empty());
+	ASSERT_TRUE(ExtractBearerToken("Bearer").empty());
+	ASSERT_TRUE(ExtractBearerToken("Basic dXNlcjpwYXNz").empty());
+	ASSERT_TRUE(ExtractBearerToken("").empty());
+}
+
+TEST(Auth, ExtractBearerToken_TolerantOfExtraSpaces)
+{
+	// Multiple OWS chars between scheme and credentials per RFC 7230 §3.2.3.
+	ASSERT_EQUALS(std::string("tok"), ExtractBearerToken("Bearer   tok"));
+}
+
+TEST(Auth, ExtractCookieValue_HappyPath)
+{
+	ASSERT_EQUALS(std::string("xyz"),
+		ExtractCookieValue("amuleapi_token=xyz", "amuleapi_token"));
+}
+
+TEST(Auth, ExtractCookieValue_OtherCookiesInWay)
+{
+	const std::string header = "foo=1; amuleapi_token=abc; bar=2";
+	ASSERT_EQUALS(std::string("abc"),
+		ExtractCookieValue(header, "amuleapi_token"));
+}
+
+TEST(Auth, ExtractCookieValue_MissingReturnsEmpty)
+{
+	ASSERT_TRUE(ExtractCookieValue("foo=1; bar=2", "amuleapi_token").empty());
+	ASSERT_TRUE(ExtractCookieValue("", "amuleapi_token").empty());
+}
+
+
+// ---------- ISO-8601 ---------------------------------------------
+
+TEST(Auth, FormatIso8601Utc_KnownTimestamp)
+{
+	// 1768523696 = 2026-01-16T00:34:56Z (verified via
+	// `date -r 1768523696 -u`); a single point exercises the standard
+	// year/month/day/hour/min/sec formatting path.
+	const std::time_t t = 1768523696;
+	ASSERT_EQUALS(std::string("2026-01-16T00:34:56Z"), FormatIso8601Utc(t));
+}
+
+TEST(Auth, FormatIso8601Utc_FixedWidth)
+{
+	// 1735734005 = 2025-01-01T12:20:05Z (verified via
+	// `date -r 1735734005 -u`). Single-digit month / day / second
+	// here all need leading zeros — pinning length=20 + trailing
+	// 'Z' catches any %d → %2d regression.
+	const std::time_t t = 1735734005;
+	const std::string s = FormatIso8601Utc(t);
+	ASSERT_EQUALS(static_cast<size_t>(20), s.size());
+	ASSERT_EQUALS('Z', s.back());
+	ASSERT_EQUALS(std::string("2025-01-01T12:20:05Z"), s);
+}
diff --git a/unittests/tests/CMakeLists.txt b/unittests/tests/CMakeLists.txt
index 1612ffa2d3..326fab1ec6 100644
--- a/unittests/tests/CMakeLists.txt
+++ b/unittests/tests/CMakeLists.txt
@@ -234,3 +234,192 @@ target_link_libraries (OtherFunctionsTest
 	mulecommon
 	CRYPTOPP::CRYPTOPP
 )
+
+
+# libwebcommon — JWT / JSON writer / route patterns. `webcommon` PUBLIC-links
+# wxWidgets::BASE and CRYPTOPP::CRYPTOPP and exposes its own headers through
+# INTERFACE_INCLUDE_DIRECTORIES, so each test target only needs to depend on
+# `muleunit` and `webcommon`.
+
+add_executable (JwtTest
+	JwtTest.cpp
+)
+add_test (NAME JwtTest COMMAND JwtTest)
+target_link_libraries (JwtTest
+	muleunit
+	webcommon
+	mulecommon
+)
+
+add_executable (JsonWriterTest
+	JsonWriterTest.cpp
+)
+add_test (NAME JsonWriterTest COMMAND JsonWriterTest)
+target_link_libraries (JsonWriterTest
+	muleunit
+	webcommon
+	mulecommon
+)
+
+add_executable (PathPatternsTest
+	PathPatternsTest.cpp
+)
+add_test (NAME PathPatternsTest COMMAND PathPatternsTest)
+target_link_libraries (PathPatternsTest
+	muleunit
+	webcommon
+	mulecommon
+)
+
+add_executable (EtagTest
+	EtagTest.cpp
+)
+add_test (NAME EtagTest COMMAND EtagTest)
+target_link_libraries (EtagTest
+	muleunit
+	webcommon
+	mulecommon
+)
+
+add_executable (StaticFsTest
+	StaticFsTest.cpp
+	${CMAKE_SOURCE_DIR}/src/webapi/StaticFs.cpp
+)
+target_include_directories (StaticFsTest
+	PRIVATE ${CMAKE_SOURCE_DIR}/src/webapi
+)
+add_test (NAME StaticFsTest COMMAND StaticFsTest)
+target_link_libraries (StaticFsTest
+	muleunit
+	mulecommon
+)
+
+add_executable (EventBusTest
+	EventBusTest.cpp
+	${CMAKE_SOURCE_DIR}/src/webapi/EventBus.cpp
+)
+target_include_directories (EventBusTest
+	PRIVATE ${CMAKE_SOURCE_DIR}/src/webapi
+)
+add_test (NAME EventBusTest COMMAND EventBusTest)
+target_link_libraries (EventBusTest
+	muleunit
+	mulecommon
+)
+
+# Tests for EmitDiffsAndUpdate's log_appended path and cold-start
+# gating. Pulls EventBus + State along with EventDiff itself — none
+# touch wxWidgets or EC, so the exe is pure stdlib + muleunit.
+add_executable (EventDiffTest
+	EventDiffTest.cpp
+	${CMAKE_SOURCE_DIR}/src/webapi/EventBus.cpp
+	${CMAKE_SOURCE_DIR}/src/webapi/EventDiff.cpp
+	${CMAKE_SOURCE_DIR}/src/webapi/State.cpp
+)
+target_include_directories (EventDiffTest
+	PRIVATE ${CMAKE_SOURCE_DIR}/src/webapi
+)
+add_test (NAME EventDiffTest COMMAND EventDiffTest)
+target_link_libraries (EventDiffTest
+	muleunit
+	mulecommon
+)
+
+# amuleapi-specific: tests CAmuleApiConfig's file-IO + mode-bit
+# enforcement. AmuleApiConfig.cpp is statically linked into the test
+# binary (rather than a webapi-side static lib) — it's a single TU and
+# the amuleapi exe is the only other consumer, so an extra library
+# target for one TU would just add noise.
+add_executable (AmuleApiConfigTest
+	AmuleApiConfigTest.cpp
+	${CMAKE_SOURCE_DIR}/src/webapi/AmuleApiConfig.cpp
+)
+add_test (NAME AmuleApiConfigTest COMMAND AmuleApiConfigTest)
+target_include_directories (AmuleApiConfigTest
+	PRIVATE ${CMAKE_SOURCE_DIR}/src/webapi
+)
+target_link_libraries (AmuleApiConfigTest
+	muleunit
+	webcommon
+	mulecommon
+	wxWidgets::BASE
+)
+
+# amuleapi auth state — revocation set, rate limiter, header
+# extraction, ISO-8601 formatter. Same vendoring pattern as the
+# Config test: Auth.cpp is pulled in directly because amuleapi is
+# the only other consumer.
+add_executable (AuthTest
+	AuthTest.cpp
+	${CMAKE_SOURCE_DIR}/src/webapi/Auth.cpp
+)
+add_test (NAME AuthTest COMMAND AuthTest)
+target_include_directories (AuthTest
+	PRIVATE ${CMAKE_SOURCE_DIR}/src/webapi
+)
+target_link_libraries (AuthTest
+	muleunit
+	webcommon
+	mulecommon
+)
+
+# amuleapi state cache — snapshot semantics + concurrent-reader
+# correctness on the shared_timed_mutex.
+add_executable (StateTest
+	StateTest.cpp
+	${CMAKE_SOURCE_DIR}/src/webapi/State.cpp
+)
+add_test (NAME StateTest COMMAND StateTest)
+target_include_directories (StateTest
+	PRIVATE ${CMAKE_SOURCE_DIR}/src/webapi
+)
+target_link_libraries (StateTest
+	muleunit
+	mulecommon
+)
+
+# amuleapi refresher — the pure EC-tag-to-State translation layer
+# (Refresher.cpp) is linkable without the CamuleapiApp dependency
+# tree because the orchestration body lives in RefresherTick.cpp
+# (kept out of this target). Tests cover the EC_TAG_FILE_REMOVED
+# delete marker, the alive-marker enqueue path, the unknown-ECID-
+# no-op defence (#713-class race), and partial-update-active.
+add_executable (RefresherTest
+	RefresherTest.cpp
+	${CMAKE_SOURCE_DIR}/src/webapi/Refresher.cpp
+	${CMAKE_SOURCE_DIR}/src/webapi/State.cpp
+	# OtherFunctions.cpp ships the `CastIto*` / `CastSecondsToHM`
+	# formatters that `CEC_StatTree_Node_Tag::GetDisplayString` pulls
+	# in via libec.a's `FormatValue`. Without this the ParseStatsTree
+	# test can't link.
+	${CMAKE_SOURCE_DIR}/src/OtherFunctions.cpp
+	# RLE.cpp ships `PartFileEncoderData` + the stateful `RLE_Data`
+	# decoder Refresher.cpp uses for `progress.parts`. Required even
+	# for tests that don't directly invoke the decoder — the public
+	# Apply{Update,Full} signatures take `std::map<ecid,
+	# PartFileEncoderData>&` so the class is part of the link.
+	${CMAKE_SOURCE_DIR}/src/RLE.cpp
+	# LoggerConsole.cpp provides the no-op DoECLogLine + theLogger
+	# symbols that libec.a's Debug build references unconditionally
+	# (ECPacket / ECSocket / ECTag debug-print paths). Release builds
+	# preprocess these calls to `do {} while(0)` via the ECLog.h
+	# define, so the symbols are unused there; macOS Debug + Ubuntu
+	# Debug builds link them in. Mirror amuleapi's own webapi/
+	# CMakeLists.txt, which already pulls this TU in.
+	${CMAKE_SOURCE_DIR}/src/LoggerConsole.cpp
+)
+add_test (NAME RefresherTest COMMAND RefresherTest)
+target_include_directories (RefresherTest
+	PRIVATE ${CMAKE_SOURCE_DIR}/src/webapi
+	PRIVATE ${CMAKE_SOURCE_DIR}/src
+	PRIVATE ${CMAKE_SOURCE_DIR}/src/include
+	PRIVATE ${CMAKE_BINARY_DIR}
+)
+target_link_libraries (RefresherTest
+	muleunit
+	ec
+	mulecommon
+	mulesocket
+	webcommon
+	wxWidgets::NET
+)
diff --git a/unittests/tests/EtagTest.cpp b/unittests/tests/EtagTest.cpp
new file mode 100644
index 0000000000..2236dc4e6b
--- /dev/null
+++ b/unittests/tests/EtagTest.cpp
@@ -0,0 +1,165 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#include <muleunit/test.h>
+
+#include "Etag.h"
+
+#include <string>
+
+
+using namespace muleunit;
+using namespace webcommon;
+
+
+DECLARE_SIMPLE(Etag)
+
+
+// ----------------------------------------------------------------------
+// `Etag()` — SHA-256 truncated to 8 bytes (16 hex chars).
+// ----------------------------------------------------------------------
+
+TEST(Etag, BareHexLength)
+{
+	// 16 hex chars regardless of body length — the truncation is the
+	// wire contract that prevents header bloat.
+	ASSERT_EQUALS(static_cast<size_t>(16), Etag("").size());
+	ASSERT_EQUALS(static_cast<size_t>(16), Etag("x").size());
+	ASSERT_EQUALS(static_cast<size_t>(16),
+		Etag(std::string(1024 * 1024, 'A')).size());
+}
+
+
+TEST(Etag, EmptyBodyKnownDigest)
+{
+	// SHA-256("") truncated to 8 bytes, lowercase hex.
+	// Reference: `printf '' | shasum -a 256` →
+	// "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+	// Leading 16 hex chars = "e3b0c44298fc1c14".
+	ASSERT_EQUALS(std::string("e3b0c44298fc1c14"), Etag(""));
+}
+
+
+TEST(Etag, DistinctBodiesProduceDistinctEtags)
+{
+	// Sanity: the truncation didn't accidentally collapse common
+	// short payloads to the same digest.
+	ASSERT_TRUE(Etag("a") != Etag("b"));
+	ASSERT_TRUE(Etag("{\"ok\":true}") != Etag("{\"ok\":false}"));
+}
+
+
+// ----------------------------------------------------------------------
+// `IfNoneMatchHits()` — fix for the bare-vs-quoted asymmetry.
+// ----------------------------------------------------------------------
+
+TEST(Etag, IfNoneMatchEmptyHeaderNoHit)
+{
+	// Absent header → cannot be a match.
+	ASSERT_FALSE(IfNoneMatchHits("", "deadbeefdeadbeef"));
+}
+
+
+TEST(Etag, IfNoneMatchBareHexHits)
+{
+	// Bare-vs-bare compare must hit — backward compatibility for
+	// clients that send unquoted validators.
+	ASSERT_TRUE(IfNoneMatchHits("deadbeefdeadbeef",
+	                            "deadbeefdeadbeef"));
+}
+
+
+TEST(Etag, IfNoneMatchQuotedHexHits)
+{
+	// RFC 7232 §2.3-canonical form: `"<hex>"`. This was the latent
+	// bug — strictly-RFC clients sending the quoted form never got
+	// 304 from the prior implementation.
+	ASSERT_TRUE(IfNoneMatchHits("\"deadbeefdeadbeef\"",
+	                            "deadbeefdeadbeef"));
+}
+
+
+TEST(Etag, IfNoneMatchWeakValidatorHits)
+{
+	// `W/"<hex>"`: weak validator. For conditional GETs we treat
+	// weak and strong as equivalent (Section 2.3.2 — opaque payload
+	// equality is what matters for 304 semantics).
+	ASSERT_TRUE(IfNoneMatchHits("W/\"deadbeefdeadbeef\"",
+	                            "deadbeefdeadbeef"));
+}
+
+
+TEST(Etag, IfNoneMatchWildcardHits)
+{
+	// `*` matches any existing representation per RFC §3.2.
+	ASSERT_TRUE(IfNoneMatchHits("*", "deadbeefdeadbeef"));
+}
+
+
+TEST(Etag, IfNoneMatchListAnyMatchWins)
+{
+	// Comma-separated list — any matching entry returns true.
+	ASSERT_TRUE(IfNoneMatchHits(
+		"\"someotheretag\", \"deadbeefdeadbeef\", \"yetanother\"",
+		"deadbeefdeadbeef"));
+	// Even with mixed strong/weak/bare.
+	ASSERT_TRUE(IfNoneMatchHits(
+		"W/\"first\", deadbeefdeadbeef",
+		"deadbeefdeadbeef"));
+}
+
+
+TEST(Etag, IfNoneMatchListNoMatchMisses)
+{
+	// None of the entries match → no hit.
+	ASSERT_FALSE(IfNoneMatchHits(
+		"\"someotheretag\", \"yetanother\"",
+		"deadbeefdeadbeef"));
+}
+
+
+TEST(Etag, IfNoneMatchWhitespaceTolerated)
+{
+	// Surrounding whitespace within list entries is stripped.
+	ASSERT_TRUE(IfNoneMatchHits("   \"deadbeefdeadbeef\"   ",
+	                            "deadbeefdeadbeef"));
+}
+
+
+TEST(Etag, IfNoneMatchHexMismatchMisses)
+{
+	// Different hex payload → no hit even with right shape.
+	ASSERT_FALSE(IfNoneMatchHits("\"feedfacefeedface\"",
+	                             "deadbeefdeadbeef"));
+}
+
+
+TEST(Etag, IfNoneMatchHexCaseSensitive)
+{
+	// RFC §2.3.2: opaque-string equality. We emit lowercase hex on
+	// the response side; clients echoing the value back must also
+	// send lowercase. Uppercase variant → no hit.
+	ASSERT_FALSE(IfNoneMatchHits("DEADBEEFDEADBEEF",
+	                             "deadbeefdeadbeef"));
+}
diff --git a/unittests/tests/EventBusTest.cpp b/unittests/tests/EventBusTest.cpp
new file mode 100644
index 0000000000..09b9128f0d
--- /dev/null
+++ b/unittests/tests/EventBusTest.cpp
@@ -0,0 +1,210 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#include <muleunit/test.h>
+
+#include "EventBus.h"
+
+#include <atomic>
+#include <chrono>
+#include <thread>
+
+
+using namespace muleunit;
+using namespace webapi;
+
+
+DECLARE_SIMPLE(EventBus)
+
+
+TEST(EventBus, EmptyBusOldestAndNewestAreZero)
+{
+	CEventBus bus;
+	ASSERT_EQUALS(static_cast<std::uint64_t>(0), bus.OldestId());
+	ASSERT_EQUALS(static_cast<std::uint64_t>(0), bus.NewestId());
+}
+
+
+TEST(EventBus, PublishAssignsMonotonicIds)
+{
+	CEventBus bus;
+	bus.Publish("a", "{}");
+	bus.Publish("b", "{}");
+	bus.Publish("c", "{}");
+	// First id is 1; ids are dense and monotonic.
+	ASSERT_EQUALS(static_cast<std::uint64_t>(1), bus.OldestId());
+	ASSERT_EQUALS(static_cast<std::uint64_t>(3), bus.NewestId());
+}
+
+
+TEST(EventBus, DrainSinceZeroReturnsEverything)
+{
+	CEventBus bus;
+	bus.Publish("a", "{\"x\":1}");
+	bus.Publish("b", "{\"x\":2}");
+
+	std::vector<Event> out;
+	const std::uint64_t high = bus.Drain(0, std::chrono::milliseconds(0), out);
+	ASSERT_EQUALS(static_cast<size_t>(2), out.size());
+	ASSERT_EQUALS(std::string("a"), out[0].name);
+	ASSERT_EQUALS(std::string("b"), out[1].name);
+	ASSERT_EQUALS(static_cast<std::uint64_t>(2), high);
+}
+
+
+TEST(EventBus, DrainSinceFiltersOlder)
+{
+	CEventBus bus;
+	bus.Publish("a", "{}");
+	bus.Publish("b", "{}");
+	bus.Publish("c", "{}");
+	std::vector<Event> out;
+	const std::uint64_t high = bus.Drain(/*since=*/1,
+	                                     std::chrono::milliseconds(0), out);
+	ASSERT_EQUALS(static_cast<size_t>(2), out.size());
+	ASSERT_EQUALS(std::string("b"), out[0].name);
+	ASSERT_EQUALS(std::string("c"), out[1].name);
+	ASSERT_EQUALS(static_cast<std::uint64_t>(3), high);
+}
+
+
+TEST(EventBus, DrainBlocksUntilPublish)
+{
+	CEventBus bus;
+	std::atomic<bool> drain_returned{false};
+	std::vector<Event> got;
+
+	std::thread waiter([&] {
+		bus.Drain(0, std::chrono::seconds(5), got);
+		drain_returned.store(true);
+	});
+
+	// Drainer should still be blocked after a beat.
+	std::this_thread::sleep_for(std::chrono::milliseconds(100));
+	ASSERT_FALSE(drain_returned.load());
+
+	// Publish — the condvar should wake the drainer in well under 5 s.
+	bus.Publish("late", "{}");
+
+	// Give a generous slack window for the wake + copy.
+	for (int i = 0; i < 50 && !drain_returned.load(); ++i) {
+		std::this_thread::sleep_for(std::chrono::milliseconds(20));
+	}
+	ASSERT_TRUE(drain_returned.load());
+	waiter.join();
+
+	ASSERT_EQUALS(static_cast<size_t>(1), got.size());
+	ASSERT_EQUALS(std::string("late"), got[0].name);
+}
+
+
+TEST(EventBus, DrainTimesOutWhenNothingPublished)
+{
+	CEventBus bus;
+	std::vector<Event> out;
+	const auto start = std::chrono::steady_clock::now();
+	const std::uint64_t high = bus.Drain(0,
+		std::chrono::milliseconds(120), out);
+	const auto elapsed = std::chrono::steady_clock::now() - start;
+
+	ASSERT_TRUE(out.empty());
+	ASSERT_EQUALS(static_cast<std::uint64_t>(0), high);
+	// The drain should have spent the full timeout waiting; 80 ms of
+	// slack to absorb scheduling jitter.
+	const auto ms = std::chrono::duration_cast<
+		std::chrono::milliseconds>(elapsed).count();
+	ASSERT_TRUE(ms >= 80);
+}
+
+
+TEST(EventBus, RingCapDropsOldestWhenFull)
+{
+	// Construct with an explicit small capacity rather than the
+	// default — the default is sized for real workloads (16K) and
+	// this test would otherwise publish 16K+ events to exercise it.
+	CEventBus bus(/*capacity=*/64);
+	const std::size_t over = bus.Capacity() + 5;
+	for (std::size_t i = 0; i < over; ++i) {
+		bus.Publish("x", "{}");
+	}
+
+	std::vector<Event> out;
+	bus.Drain(0, std::chrono::milliseconds(0), out);
+	ASSERT_EQUALS(bus.Capacity(), out.size());
+
+	// OldestId is the first id we STILL have (= ids dropped + 1).
+	const std::uint64_t expected_oldest = (over - bus.Capacity()) + 1;
+	ASSERT_EQUALS(expected_oldest, bus.OldestId());
+	ASSERT_EQUALS(static_cast<std::uint64_t>(over), bus.NewestId());
+}
+
+
+TEST(EventBus, ExplicitCapacityHonored)
+{
+	CEventBus bus(/*capacity=*/256);
+	ASSERT_EQUALS(static_cast<std::size_t>(256), bus.Capacity());
+}
+
+
+TEST(EventBus, BelowMinCapacityIsClampedUp)
+{
+	// Operator config below the floor (e.g. capacity=1) is clamped
+	// to kMinCapacity. Without the clamp the bus would effectively
+	// disable replay; the floor guarantees a meaningful window.
+	CEventBus bus(/*capacity=*/1);
+	ASSERT_EQUALS(CEventBus::kMinCapacity, bus.Capacity());
+}
+
+
+TEST(EventBus, ConcurrentPublishersHaveDistinctIds)
+{
+	CEventBus bus;
+	const int per_thread = 50;
+	const int n_threads  = 4;
+	std::vector<std::thread> ths;
+	for (int t = 0; t < n_threads; ++t) {
+		ths.emplace_back([&] {
+			for (int i = 0; i < per_thread; ++i) {
+				bus.Publish("p", "{}");
+			}
+		});
+	}
+	for (auto &t : ths) t.join();
+
+	const int total = per_thread * n_threads;
+	// We can have dropped some if total > capacity; what's *guaranteed*
+	// is the newest id == total (every Publish atomically grabbed a
+	// unique id).
+	ASSERT_EQUALS(static_cast<std::uint64_t>(total), bus.NewestId());
+
+	std::vector<Event> out;
+	bus.Drain(0, std::chrono::milliseconds(0), out);
+	// All retained ids are unique and dense in their tail of the
+	// monotonic sequence.
+	std::uint64_t prev = 0;
+	for (const auto &ev : out) {
+		ASSERT_TRUE(ev.id > prev);
+		prev = ev.id;
+	}
+}
diff --git a/unittests/tests/EventDiffTest.cpp b/unittests/tests/EventDiffTest.cpp
new file mode 100644
index 0000000000..5913815b61
--- /dev/null
+++ b/unittests/tests/EventDiffTest.cpp
@@ -0,0 +1,211 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#include <muleunit/test.h>
+
+#include "EventBus.h"
+#include "EventDiff.h"
+#include "State.h"
+
+#include <chrono>
+#include <string>
+#include <vector>
+
+
+using namespace muleunit;
+using namespace webapi;
+
+
+DECLARE_SIMPLE(EventDiff)
+
+
+// Drain `bus` non-blockingly and return all events in id order.
+static std::vector<Event> DrainAll(CEventBus &bus)
+{
+	std::vector<Event> out;
+	bus.Drain(0, std::chrono::milliseconds(0), out);
+	return out;
+}
+
+
+// log_appended cold-start: the first tick must not emit log_appended
+// for pre-existing lines (clients GET /api/v0/logs/amule for the
+// history; the event channel is live-tail only).
+TEST(EventDiff, LogAppendedColdStartSilent)
+{
+	CState state;
+	state.AppendAmuleLog({"old line 1\n", "old line 2\n"});
+	CEventBus bus;
+	LastSeenState prev;
+
+	EmitDiffsAndUpdate(bus, prev, state);
+
+	const auto drained = DrainAll(bus);
+	for (const auto &ev : drained) {
+		ASSERT_TRUE(ev.name != "log_appended");
+	}
+	// Baseline counter must equal the pre-existing log size so the
+	// next tick's diff sees zero new lines until amuled actually
+	// logs something.
+	ASSERT_EQUALS(static_cast<std::size_t>(2), prev.amule_log_count);
+	ASSERT_TRUE(prev.amule_log_initialised);
+}
+
+
+// After cold-start, a single appended line publishes exactly one
+// log_appended event with the new line in `lines`.
+TEST(EventDiff, LogAppendedFiresOnSingleNewLine)
+{
+	CState state;
+	state.AppendAmuleLog({"old line\n"});
+	CEventBus bus;
+	LastSeenState prev;
+
+	// Tick 1: baseline.
+	EmitDiffsAndUpdate(bus, prev, state);
+	// Tick 2: amuled appended a fresh line. Expect log_appended.
+	state.AppendAmuleLog({"new line\n"});
+	EmitDiffsAndUpdate(bus, prev, state);
+
+	const auto drained = DrainAll(bus);
+	int log_events = 0;
+	std::string payload;
+	for (const auto &ev : drained) {
+		if (ev.name == "log_appended") {
+			++log_events;
+			payload = ev.data;
+		}
+	}
+	ASSERT_EQUALS(1, log_events);
+	// Payload must contain the new line content and NOT the old one.
+	ASSERT_TRUE(payload.find("new line") != std::string::npos);
+	ASSERT_TRUE(payload.find("old line") == std::string::npos);
+	// Counter advanced to 2.
+	ASSERT_EQUALS(static_cast<std::size_t>(2), prev.amule_log_count);
+}
+
+
+// A batch of multiple new lines lands in one event with a `lines`
+// array — never N separate events. Bus traffic ≪ line traffic.
+TEST(EventDiff, LogAppendedBatchesMultipleLinesIntoOneEvent)
+{
+	CState state;
+	CEventBus bus;
+	LastSeenState prev;
+
+	EmitDiffsAndUpdate(bus, prev, state);  // cold-start, log is empty
+	state.AppendAmuleLog({"A\n", "B\n", "C\n"});
+	EmitDiffsAndUpdate(bus, prev, state);
+
+	const auto drained = DrainAll(bus);
+	int log_events = 0;
+	std::string payload;
+	for (const auto &ev : drained) {
+		if (ev.name == "log_appended") {
+			++log_events;
+			payload = ev.data;
+		}
+	}
+	ASSERT_EQUALS(1, log_events);
+	ASSERT_TRUE(payload.find("\"A") != std::string::npos);
+	ASSERT_TRUE(payload.find("\"B") != std::string::npos);
+	ASSERT_TRUE(payload.find("\"C") != std::string::npos);
+	ASSERT_EQUALS(static_cast<std::size_t>(3), prev.amule_log_count);
+}
+
+
+// Idle ticks (no new lines) must not publish log_appended.
+TEST(EventDiff, LogAppendedSilentOnIdleTick)
+{
+	CState state;
+	state.AppendAmuleLog({"baseline\n"});
+	CEventBus bus;
+	LastSeenState prev;
+
+	EmitDiffsAndUpdate(bus, prev, state);
+	(void)DrainAll(bus);   // discard cold-start events
+
+	EmitDiffsAndUpdate(bus, prev, state);   // idle
+	EmitDiffsAndUpdate(bus, prev, state);   // idle
+
+	const auto drained = DrainAll(bus);
+	for (const auto &ev : drained) {
+		ASSERT_TRUE(ev.name != "log_appended");
+	}
+}
+
+
+// JSON escaping: a line containing characters that need JSON-escaping
+// (backslash, double quote, control chars) must produce a valid JSON
+// payload. The EscJson helper backing this is the same one the
+// snapshot payloads use; covering it here pins the contract for
+// the log path specifically.
+TEST(EventDiff, LogAppendedEscapesJsonHazards)
+{
+	CState state;
+	CEventBus bus;
+	LastSeenState prev;
+	EmitDiffsAndUpdate(bus, prev, state);
+
+	// A line with: a quote, a backslash, a control char.
+	state.AppendAmuleLog({std::string("hi \"quoted\\path\" \x01 done\n")});
+	EmitDiffsAndUpdate(bus, prev, state);
+
+	const auto drained = DrainAll(bus);
+	std::string payload;
+	for (const auto &ev : drained) {
+		if (ev.name == "log_appended") payload = ev.data;
+	}
+	// The raw characters must NOT appear unescaped in the payload.
+	// `\"` must become `\\\"`, `\\` must become `\\\\`, `\x01` must
+	// be `\\u0001`.
+	ASSERT_TRUE(payload.find("\\\"") != std::string::npos);
+	ASSERT_TRUE(payload.find("\\\\") != std::string::npos);
+	ASSERT_TRUE(payload.find("\\u0001") != std::string::npos);
+}
+
+
+// Truncation case (DELETE /logs/amule shrinks the vector): the diff
+// must silently resync the baseline counter without publishing.
+TEST(EventDiff, LogAppendedSilentOnTruncation)
+{
+	CState state;
+	state.AppendAmuleLog({"a\n", "b\n", "c\n"});
+	CEventBus bus;
+	LastSeenState prev;
+
+	EmitDiffsAndUpdate(bus, prev, state);
+	ASSERT_EQUALS(static_cast<std::size_t>(3), prev.amule_log_count);
+
+	// Force a smaller log: rebuild State with a shorter vector.
+	CState state2;
+	state2.AppendAmuleLog({"a\n"});
+	EmitDiffsAndUpdate(bus, prev, state2);
+
+	const auto drained = DrainAll(bus);
+	for (const auto &ev : drained) {
+		ASSERT_TRUE(ev.name != "log_appended");
+	}
+	ASSERT_EQUALS(static_cast<std::size_t>(1), prev.amule_log_count);
+}
diff --git a/unittests/tests/JsonWriterTest.cpp b/unittests/tests/JsonWriterTest.cpp
new file mode 100644
index 0000000000..10d7ae00f5
--- /dev/null
+++ b/unittests/tests/JsonWriterTest.cpp
@@ -0,0 +1,266 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#include <muleunit/test.h>
+#include "JsonWriter.h"
+
+#include <cmath>
+#include <limits>
+
+using namespace muleunit;
+
+
+DECLARE_SIMPLE(JsonWriter)
+
+
+TEST(JsonWriter, EmptyObject)
+{
+	CJsonWriter w;
+	w.BeginObject();
+	w.EndObject();
+	ASSERT_EQUALS(wxString("{}"), w.GetBuffer());
+}
+
+
+TEST(JsonWriter, EmptyArray)
+{
+	CJsonWriter w;
+	w.BeginArray();
+	w.EndArray();
+	ASSERT_EQUALS(wxString("[]"), w.GetBuffer());
+}
+
+
+TEST(JsonWriter, ObjectWithStringValue)
+{
+	CJsonWriter w;
+	w.BeginObject();
+	w.Key("app"); w.ValueString("aMule");
+	w.EndObject();
+	ASSERT_EQUALS(wxString("{\"app\":\"aMule\"}"), w.GetBuffer());
+}
+
+
+TEST(JsonWriter, ObjectWithMultipleKeys)
+{
+	CJsonWriter w;
+	w.BeginObject();
+	w.Key("app");     w.ValueString("aMule");
+	w.Key("version"); w.ValueString("2.3.3");
+	w.Key("api");     w.ValueString("v0.1");
+	w.EndObject();
+	ASSERT_EQUALS(
+		wxString("{\"app\":\"aMule\",\"version\":\"2.3.3\",\"api\":\"v0.1\"}"),
+		w.GetBuffer());
+}
+
+
+TEST(JsonWriter, Primitives)
+{
+	CJsonWriter w;
+	w.BeginObject();
+	w.Key("n");   w.ValueNull();
+	w.Key("t");   w.ValueBool(true);
+	w.Key("f");   w.ValueBool(false);
+	w.Key("i");   w.ValueInt(-42);
+	w.Key("u");   w.ValueUInt(uint64_t(42));
+	w.EndObject();
+	ASSERT_EQUALS(
+		wxString("{\"n\":null,\"t\":true,\"f\":false,\"i\":-42,\"u\":42}"),
+		w.GetBuffer());
+}
+
+
+TEST(JsonWriter, IntegerBoundaries)
+{
+	CJsonWriter w;
+	w.BeginArray();
+	w.ValueInt(std::numeric_limits<int64_t>::min());
+	w.ValueInt(std::numeric_limits<int64_t>::max());
+	w.ValueUInt(std::numeric_limits<uint64_t>::max());
+	w.EndArray();
+	ASSERT_EQUALS(
+		wxString("[-9223372036854775808,9223372036854775807,18446744073709551615]"),
+		w.GetBuffer());
+}
+
+
+TEST(JsonWriter, DoubleSpecials)
+{
+	// NaN, +Inf, -Inf are not representable in JSON; the writer emits null.
+	CJsonWriter w;
+	w.BeginArray();
+	w.ValueDouble(std::nan(""));
+	w.ValueDouble(std::numeric_limits<double>::infinity());
+	w.ValueDouble(-std::numeric_limits<double>::infinity());
+	w.EndArray();
+	ASSERT_EQUALS(wxString("[null,null,null]"), w.GetBuffer());
+}
+
+
+TEST(JsonWriter, NestedObject)
+{
+	CJsonWriter w;
+	w.BeginObject();
+	w.Key("outer");
+	w.BeginObject();
+	w.Key("inner"); w.ValueString("v");
+	w.EndObject();
+	w.EndObject();
+	ASSERT_EQUALS(wxString("{\"outer\":{\"inner\":\"v\"}}"), w.GetBuffer());
+}
+
+
+TEST(JsonWriter, ArrayOfObjects)
+{
+	CJsonWriter w;
+	w.BeginObject();
+	w.Key("items");
+	w.BeginArray();
+	w.BeginObject(); w.Key("k"); w.ValueInt(1); w.EndObject();
+	w.BeginObject(); w.Key("k"); w.ValueInt(2); w.EndObject();
+	w.EndArray();
+	w.EndObject();
+	ASSERT_EQUALS(
+		wxString("{\"items\":[{\"k\":1},{\"k\":2}]}"),
+		w.GetBuffer());
+}
+
+
+TEST(JsonWriter, EscapesQuoteAndBackslash)
+{
+	CJsonWriter w;
+	w.ValueString(wxString::FromUTF8("a\"b\\c"));
+	ASSERT_EQUALS(wxString("\"a\\\"b\\\\c\""), w.GetBuffer());
+}
+
+
+TEST(JsonWriter, EscapesShortControlChars)
+{
+	CJsonWriter w;
+	w.ValueString(wxString::FromUTF8("\b\f\n\r\t"));
+	ASSERT_EQUALS(wxString("\"\\b\\f\\n\\r\\t\""), w.GetBuffer());
+}
+
+
+TEST(JsonWriter, EscapesGenericControlChars)
+{
+	// Control chars without short forms get \uXXXX. DEL (0x7F) is treated
+	// the same so it never lands in the output verbatim.
+	CJsonWriter w;
+	w.BeginArray();
+	w.ValueString(wxString(wxUniChar(uint32_t(0x00))));
+	w.ValueString(wxString(wxUniChar(uint32_t(0x01))));
+	w.ValueString(wxString(wxUniChar(uint32_t(0x1F))));
+	w.ValueString(wxString(wxUniChar(uint32_t(0x7F))));
+	w.EndArray();
+	ASSERT_EQUALS(
+		wxString("[\"\\u0000\",\"\\u0001\",\"\\u001f\",\"\\u007f\"]"),
+		w.GetBuffer());
+}
+
+
+TEST(JsonWriter, SupplementaryPlaneAsSurrogatePair)
+{
+	// U+1F600 (GRINNING FACE) is in the supplementary plane; it must be
+	// emitted as the UTF-16 surrogate pair 😀.
+	CJsonWriter w;
+	w.ValueString(wxString(wxUniChar(uint32_t(0x1F600))));
+	ASSERT_EQUALS(wxString("\"\\ud83d\\ude00\""), w.GetBuffer());
+}
+
+
+TEST(JsonWriter, BmpNonAsciiEmittedVerbatim)
+{
+	// Non-control codepoints in the BMP are passed through as wxString
+	// content. The serializer encodes the whole buffer as UTF-8 at
+	// flush time; here we just verify the round trip is invariant.
+	const wxString input = wxString::FromUTF8("\xD0\xBF\xD1\x80\xD0\xB8\xD0\xB2\xD0\xB5\xD1\x82"); // "привет"
+	CJsonWriter w;
+	w.ValueString(input);
+	// The wxString contains exactly: " <6 cyrillic chars> "
+	wxString expected;
+	expected += wxT("\"");
+	expected += input;
+	expected += wxT("\"");
+	ASSERT_EQUALS(expected, w.GetBuffer());
+}
+
+
+TEST(JsonWriter, KeyEscaping)
+{
+	// Keys go through the same escaping path as values. A key containing
+	// a quote must be escaped or the output is invalid JSON.
+	CJsonWriter w;
+	w.BeginObject();
+	w.Key(wxString::FromUTF8("a\"b"));
+	w.ValueInt(1);
+	w.EndObject();
+	ASSERT_EQUALS(wxString("{\"a\\\"b\":1}"), w.GetBuffer());
+}
+
+
+TEST(JsonWriter, ValueRawFragment)
+{
+	// A pre-formatted JSON fragment is appended verbatim. Caller is
+	// responsible for ensuring it's valid JSON; the writer only tracks
+	// whether a comma is needed before/after.
+	CJsonWriter w;
+	w.BeginObject();
+	w.Key("pre"); w.ValueRaw(wxT("[1,2,3]"));
+	w.Key("post"); w.ValueInt(4);
+	w.EndObject();
+	ASSERT_EQUALS(wxString("{\"pre\":[1,2,3],\"post\":4}"), w.GetBuffer());
+}
+
+
+TEST(JsonWriter, ExternalBuffer)
+{
+	// The writer can append into a caller-owned buffer instead of its
+	// own. Used when composing a response from multiple writers.
+	wxString shared;
+	shared += wxT("prefix:");
+	{
+		CJsonWriter w(&shared);
+		w.BeginObject();
+		w.Key("x"); w.ValueInt(1);
+		w.EndObject();
+	}
+	ASSERT_EQUALS(wxString("prefix:{\"x\":1}"), shared);
+}
+
+
+TEST(JsonWriter, LargeString)
+{
+	// 50 KB string of printable ASCII should encode in linear time with
+	// the only overhead being the surrounding quotes.
+	wxString big(wxT('x'), 50000);
+	CJsonWriter w;
+	w.ValueString(big);
+	wxString expected;
+	expected += wxT("\"");
+	expected += big;
+	expected += wxT("\"");
+	ASSERT_EQUALS(expected, w.GetBuffer());
+}
diff --git a/unittests/tests/JwtTest.cpp b/unittests/tests/JwtTest.cpp
new file mode 100644
index 0000000000..e40e1d2a9a
--- /dev/null
+++ b/unittests/tests/JwtTest.cpp
@@ -0,0 +1,545 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#include <muleunit/test.h>
+#include "Jwt.h"
+
+#include <cryptopp/hmac.h>
+#include <cryptopp/sha.h>
+
+#include <ctime>
+#include <set>
+#include <string>
+#include <vector>
+
+using namespace muleunit;
+
+
+DECLARE(Jwt)
+	std::vector<unsigned char> MakeSecret(unsigned char fill)
+	{
+		return std::vector<unsigned char>(32, fill);
+	}
+END_DECLARE;
+
+
+TEST(Jwt, IssueProducesThreeDottedParts)
+{
+	CJwt auth(MakeSecret(0xAB));
+	const std::string token = auth.Issue(Role::ADMIN).token;
+	// Header.Payload.Signature — exactly two dots.
+	int dots = 0;
+	for (size_t i = 0; i < token.size(); ++i) {
+		if (token[i] == '.') ++dots;
+	}
+	ASSERT_EQUALS(2, dots);
+	ASSERT_TRUE(!token.empty());
+}
+
+
+TEST(Jwt, RoundtripAdmin)
+{
+	CJwt auth(MakeSecret(0x11));
+	const CJwt::IssuedToken issued = auth.Issue(Role::ADMIN);
+
+	CJwt::VerifyResult r;
+	ASSERT_TRUE(auth.Verify(issued.token, r));
+	ASSERT_TRUE(r.role == Role::ADMIN);
+	ASSERT_EQUALS(issued.expires_at, r.exp);
+}
+
+
+TEST(Jwt, RoundtripGuest)
+{
+	CJwt auth(MakeSecret(0x22));
+	const CJwt::IssuedToken issued = auth.Issue(Role::GUEST);
+
+	CJwt::VerifyResult r;
+	ASSERT_TRUE(auth.Verify(issued.token, r));
+	ASSERT_TRUE(r.role == Role::GUEST);
+}
+
+
+TEST(Jwt, ExpiryIs24Hours)
+{
+	CJwt auth(MakeSecret(0x33));
+	const std::time_t before = std::time(nullptr);
+	const CJwt::IssuedToken issued = auth.Issue(Role::ADMIN);
+	const std::time_t after  = std::time(nullptr);
+
+	// expires_at must be between [before+86400, after+86400] — same-
+	// second tolerance for the clock tick.
+	const std::time_t lifetime = 24 * 60 * 60;
+	ASSERT_TRUE(issued.expires_at >= before + lifetime);
+	ASSERT_TRUE(issued.expires_at <= after  + lifetime);
+}
+
+
+TEST(Jwt, IssueEmitsJti)
+{
+	CJwt auth(MakeSecret(0x10));
+	const CJwt::IssuedToken issued = auth.Issue(Role::ADMIN);
+	// 128-bit jti → 22 base64url chars (16 bytes ÷ 3 × 4 = 21.33 → 22).
+	ASSERT_FALSE(issued.jti.empty());
+	ASSERT_EQUALS(static_cast<size_t>(22), issued.jti.size());
+}
+
+
+TEST(Jwt, IssueProducesUniqueJti)
+{
+	// 128 random bits gives 1-in-2^64 collision odds across a single
+	// instance's lifetime. Across 1000 issues we'd need ~2^77 calls
+	// before a collision becomes likely; 1000 is comfortably in the
+	// "never sees a dupe" range and catches any RNG-reset bug.
+	CJwt auth(MakeSecret(0x12));
+	std::set<std::string> seen;
+	for (int i = 0; i < 1000; ++i) {
+		const std::string jti = auth.Issue(Role::ADMIN).jti;
+		ASSERT_TRUE(seen.insert(jti).second);
+	}
+}
+
+
+TEST(Jwt, VerifyRecoversJti)
+{
+	CJwt auth(MakeSecret(0x13));
+	const CJwt::IssuedToken issued = auth.Issue(Role::ADMIN);
+
+	CJwt::VerifyResult r;
+	ASSERT_TRUE(auth.Verify(issued.token, r));
+	ASSERT_EQUALS(issued.jti, r.jti);
+}
+
+
+TEST(Jwt, TamperedSignatureRejected)
+{
+	CJwt auth(MakeSecret(0x44));
+	std::string token = auth.Issue(Role::ADMIN).token;
+
+	// Flip the last character of the signature. base64url alphabet
+	// rotation: any non-equal char.
+	token.back() = (token.back() == 'A') ? 'B' : 'A';
+
+	CJwt::VerifyResult r;
+	ASSERT_FALSE(auth.Verify(token, r));
+}
+
+
+TEST(Jwt, TamperedPayloadRejected)
+{
+	CJwt auth(MakeSecret(0x55));
+	std::string token = auth.Issue(Role::GUEST).token;
+
+	// Flip a payload byte (between the two dots) so the HMAC mismatches.
+	const size_t first_dot  = token.find('.');
+	const size_t second_dot = token.find('.', first_dot + 1);
+	const size_t mid = (first_dot + second_dot) / 2;
+	token[mid] = (token[mid] == 'X') ? 'Y' : 'X';
+
+	CJwt::VerifyResult r;
+	ASSERT_FALSE(auth.Verify(token, r));
+}
+
+
+TEST(Jwt, WrongSecretRejected)
+{
+	CJwt issuer(MakeSecret(0x66));
+	CJwt verifier(MakeSecret(0x67));   // different secret
+
+	const std::string token = issuer.Issue(Role::ADMIN).token;
+	CJwt::VerifyResult r;
+	ASSERT_FALSE(verifier.Verify(token, r));
+}
+
+
+TEST(Jwt, MalformedNoDotsRejected)
+{
+	CJwt auth(MakeSecret(0x77));
+	CJwt::VerifyResult r;
+	ASSERT_FALSE(auth.Verify("nodotshere", r));
+	ASSERT_FALSE(auth.Verify("only.one", r));
+	ASSERT_FALSE(auth.Verify("too.many.dots.here", r));
+	ASSERT_FALSE(auth.Verify("", r));
+}
+
+
+TEST(Jwt, MalformedBase64Rejected)
+{
+	// Each section has invalid base64url chars (`=` / `+` aren't in
+	// the b64url alphabet). The test pins "malformed input gets
+	// rejected" without claiming WHICH layer caught it — currently
+	// the MAC compare bails on length mismatch, but if you reorder
+	// the verify pipeline the test still holds.
+	CJwt auth(MakeSecret(0x88));
+	CJwt::VerifyResult r;
+	ASSERT_FALSE(auth.Verify("!!!.bbb.ccc", r));
+	ASSERT_FALSE(auth.Verify("aaa.!!!.ccc", r));
+	ASSERT_FALSE(auth.Verify("aaa.bbb.!!!", r));
+}
+
+
+// --- Header-validation tests (alg-confusion defence) ----------------
+//
+// These tests build a custom JWT byte-for-byte: an arbitrary header
+// + payload + the *correct* HMAC-SHA-256 signature using the test
+// secret. That means the MAC compare succeeds and we reach the
+// header alg/typ check inside Verify(). If the check is ever
+// regressed (e.g. someone removes it for "performance"), these
+// tests start failing.
+
+namespace {
+
+const char b64_alphabet[] =
+	"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+
+std::string Base64UrlEncodeForTest(const unsigned char *data, size_t len)
+{
+	std::string out;
+	out.reserve(((len + 2) / 3) * 4);
+	for (size_t i = 0; i < len; i += 3) {
+		const unsigned b0 = data[i];
+		const unsigned b1 = (i + 1 < len) ? data[i + 1] : 0;
+		const unsigned b2 = (i + 2 < len) ? data[i + 2] : 0;
+		out += b64_alphabet[ (b0 >> 2) & 0x3f ];
+		out += b64_alphabet[ ((b0 << 4) | (b1 >> 4)) & 0x3f ];
+		if (i + 1 < len) out += b64_alphabet[ ((b1 << 2) | (b2 >> 6)) & 0x3f ];
+		if (i + 2 < len) out += b64_alphabet[ b2 & 0x3f ];
+	}
+	return out;
+}
+
+std::string CraftToken(const std::vector<unsigned char> &secret,
+                       const std::string &header_json,
+                       const std::string &payload_json)
+{
+	const std::string h_b64 = Base64UrlEncodeForTest(
+		reinterpret_cast<const unsigned char *>(header_json.data()),
+		header_json.size());
+	const std::string p_b64 = Base64UrlEncodeForTest(
+		reinterpret_cast<const unsigned char *>(payload_json.data()),
+		payload_json.size());
+	const std::string signing_input = h_b64 + "." + p_b64;
+	unsigned char mac[CryptoPP::SHA256::DIGESTSIZE];
+	CryptoPP::HMAC<CryptoPP::SHA256> hmac(
+		secret.empty() ? nullptr : secret.data(), secret.size());
+	hmac.Update(reinterpret_cast<const unsigned char *>(signing_input.data()),
+	            signing_input.size());
+	hmac.Final(mac);
+	const std::string sig = Base64UrlEncodeForTest(mac, sizeof(mac));
+	return signing_input + "." + sig;
+}
+
+}  // namespace
+
+
+TEST(Jwt, AlgNoneRejectedEvenWithValidHs256Mac)
+{
+	const auto secret = MakeSecret(0x99);
+	CJwt auth(secret);
+	// Header says alg:none, signature is a valid HS256 MAC against the
+	// test secret. Verify must still reject because alg != HS256.
+	const std::string token = CraftToken(
+		secret,
+		"{\"alg\":\"none\",\"typ\":\"JWT\"}",
+		"{\"role\":\"admin\",\"exp\":9999999999,\"jti\":\"t\"}");
+	CJwt::VerifyResult r;
+	ASSERT_FALSE(auth.Verify(token, r));
+}
+
+
+TEST(Jwt, AlgHs512RejectedEvenWithValidHs256Mac)
+{
+	const auto secret = MakeSecret(0xAA);
+	CJwt auth(secret);
+	const std::string token = CraftToken(
+		secret,
+		"{\"alg\":\"HS512\",\"typ\":\"JWT\"}",
+		"{\"role\":\"admin\",\"exp\":9999999999,\"jti\":\"t\"}");
+	CJwt::VerifyResult r;
+	ASSERT_FALSE(auth.Verify(token, r));
+}
+
+
+TEST(Jwt, AlgRs256RejectedEvenWithValidHs256Mac)
+{
+	const auto secret = MakeSecret(0xBB);
+	CJwt auth(secret);
+	const std::string token = CraftToken(
+		secret,
+		"{\"alg\":\"RS256\",\"typ\":\"JWT\"}",
+		"{\"role\":\"admin\",\"exp\":9999999999,\"jti\":\"t\"}");
+	CJwt::VerifyResult r;
+	ASSERT_FALSE(auth.Verify(token, r));
+}
+
+
+TEST(Jwt, MissingAlgRejected)
+{
+	const auto secret = MakeSecret(0xCC);
+	CJwt auth(secret);
+	const std::string token = CraftToken(
+		secret,
+		"{\"typ\":\"JWT\"}",
+		"{\"role\":\"admin\",\"exp\":9999999999,\"jti\":\"t\"}");
+	CJwt::VerifyResult r;
+	ASSERT_FALSE(auth.Verify(token, r));
+}
+
+
+TEST(Jwt, WrongTypRejected)
+{
+	const auto secret = MakeSecret(0xDD);
+	CJwt auth(secret);
+	// typ is optional in RFC 7519, but if present it MUST be "JWT".
+	const std::string token = CraftToken(
+		secret,
+		"{\"alg\":\"HS256\",\"typ\":\"not-a-jwt\"}",
+		"{\"role\":\"admin\",\"exp\":9999999999,\"jti\":\"t\"}");
+	CJwt::VerifyResult r;
+	ASSERT_FALSE(auth.Verify(token, r));
+}
+
+
+TEST(Jwt, ExpInPastRejected)
+{
+	const auto secret = MakeSecret(0xEE);
+	CJwt auth(secret);
+	// Yesterday — Verify must reject expired tokens regardless of MAC.
+	const std::time_t yesterday = std::time(nullptr) - 86400;
+	const std::string token = CraftToken(
+		secret,
+		"{\"alg\":\"HS256\",\"typ\":\"JWT\"}",
+		std::string("{\"role\":\"admin\",\"exp\":")
+		    + std::to_string(yesterday) + ",\"jti\":\"t\"}");
+	CJwt::VerifyResult r;
+	ASSERT_FALSE(auth.Verify(token, r));
+}
+
+
+TEST(Jwt, MalformedPayloadJsonRejected)
+{
+	const auto secret = MakeSecret(0xFF);
+	CJwt auth(secret);
+	// Valid HS256 MAC but the payload isn't valid JSON.
+	const std::string token = CraftToken(
+		secret,
+		"{\"alg\":\"HS256\",\"typ\":\"JWT\"}",
+		"not json at all");
+	CJwt::VerifyResult r;
+	ASSERT_FALSE(auth.Verify(token, r));
+}
+
+
+TEST(Jwt, MissingJtiRejected)
+{
+	// Crafted token with a valid HS256 MAC, valid header, valid
+	// role/exp — but no `jti` claim. amuleapi's revocation list
+	// keys off jti, so a token without one would create a hole in
+	// the revocation check; Verify() must refuse to admit one.
+	const auto secret = MakeSecret(0x01);
+	CJwt auth(secret);
+	const std::string token = CraftToken(
+		secret,
+		"{\"alg\":\"HS256\",\"typ\":\"JWT\"}",
+		"{\"role\":\"admin\",\"exp\":9999999999}");
+	CJwt::VerifyResult r;
+	ASSERT_FALSE(auth.Verify(token, r));
+}
+
+
+TEST(Jwt, EmptyJtiRejected)
+{
+	// Crafted token with an empty `jti` string. The revocation list
+	// keys off jti; an empty key collides for every issuer of an
+	// empty-jti token, so Verify() must refuse.
+	const auto secret = MakeSecret(0x02);
+	CJwt auth(secret);
+	// iat + 1h exp so the mandatory-iat + lifetime-cap checks both
+	// pass and the empty-jti check is the only available reject
+	// path.
+	const std::time_t now = std::time(nullptr);
+	const std::string token = CraftToken(
+		secret,
+		"{\"alg\":\"HS256\",\"typ\":\"JWT\"}",
+		std::string("{\"role\":\"admin\",\"iat\":")
+		    + std::to_string(now) + ",\"exp\":"
+		    + std::to_string(now + 3600) + ",\"jti\":\"\"}");
+	CJwt::VerifyResult r;
+	ASSERT_FALSE(auth.Verify(token, r));
+}
+
+
+TEST(Jwt, MissingIatRejected)
+{
+	// Without an iat claim a token has unbounded lifetime — an
+	// attacker who somehow gained mint capability could otherwise
+	// issue a token with exp = year-2100 and bypass the lifetime
+	// cap entirely. Mandatory iat closes the door.
+	const auto secret = MakeSecret(0x03);
+	CJwt auth(secret);
+	const std::time_t now = std::time(nullptr);
+	const std::string token = CraftToken(
+		secret,
+		"{\"alg\":\"HS256\",\"typ\":\"JWT\"}",
+		std::string("{\"role\":\"admin\",\"exp\":")
+		    + std::to_string(now + 3600) + ",\"jti\":\"t\"}");
+	CJwt::VerifyResult r;
+	ASSERT_FALSE(auth.Verify(token, r));
+}
+
+
+TEST(Jwt, ExpIatLifetimeCapExceeded)
+{
+	// iat present + exp within the same future window, but the
+	// total (exp - iat) is two days — well past the 24-hour
+	// TOKEN_LIFETIME_SECONDS + skew. Verify must refuse: even
+	// with the secret compromised, a hostile mint can't outrun
+	// the lifetime cap.
+	const auto secret = MakeSecret(0x04);
+	CJwt auth(secret);
+	const std::time_t now = std::time(nullptr);
+	const std::time_t two_days = 2 * 24 * 60 * 60;
+	const std::string token = CraftToken(
+		secret,
+		"{\"alg\":\"HS256\",\"typ\":\"JWT\"}",
+		std::string("{\"role\":\"admin\",\"iat\":")
+		    + std::to_string(now) + ",\"exp\":"
+		    + std::to_string(now + two_days) + ",\"jti\":\"t\"}");
+	CJwt::VerifyResult r;
+	ASSERT_FALSE(auth.Verify(token, r));
+}
+
+
+// --- Base64UrlDecode structural-invariant boundary tests ------------
+//
+// Each test crafts a token whose signing input is malformed in a way
+// Base64UrlDecode is supposed to catch, then signs THAT signing input
+// with the matching HMAC so the constant-time MAC compare passes and
+// Verify() actually reaches Base64UrlDecode. Without the boundary
+// guards, Verify() would accept the malformed token; the asserts pin
+// the rejection in place.
+//
+// Two invariants the impl guards (Jwt.cpp:94-100):
+//  * len % 4 == 1 — impossible for any valid base64url string
+//  * non-zero residue bits — `len % 4 == 2/3` leaves 4/2 trailing
+//    bits that a valid encoder always emits as 0
+
+TEST(Jwt, Base64UrlDecodeRejectsLenMod4EqualsOne)
+{
+	const auto secret = MakeSecret(0xA7);
+	CJwt auth(secret);
+	// header section has length % 4 == 1 (9 chars). Any 9-char string
+	// drawn from the b64url alphabet works; the decoder rejects on
+	// size alone before inspecting the bytes.
+	const std::string h_b64 = "AAAAAAAAA";    // 9 chars
+	const std::string p_b64 = "AAAA";         // 4 chars (mod 4 == 0)
+	const std::string signing_input = h_b64 + "." + p_b64;
+	unsigned char mac[CryptoPP::SHA256::DIGESTSIZE];
+	CryptoPP::HMAC<CryptoPP::SHA256> hmac(secret.data(), secret.size());
+	hmac.Update(reinterpret_cast<const unsigned char *>(signing_input.data()),
+	            signing_input.size());
+	hmac.Final(mac);
+	const std::string sig = Base64UrlEncodeForTest(mac, sizeof(mac));
+	const std::string token = signing_input + "." + sig;
+	CJwt::VerifyResult r;
+	ASSERT_FALSE(auth.Verify(token, r));
+}
+
+
+TEST(Jwt, Base64UrlDecodeRejectsNonZeroResidueBits)
+{
+	const auto secret = MakeSecret(0xA8);
+	CJwt auth(secret);
+	// 6-char b64url (len % 4 == 2) decodes to 1 byte and leaves 4
+	// trailing bits that a valid encoder always emits as 0. "AAAAAB"
+	// → 000000 000000 000000 000000 000000 000001 → 1 byte 0x00 +
+	// residue 0001. Decoder must reject the non-zero residue.
+	const std::string h_b64 = "AAAAAB";
+	const std::string p_b64 = "AAAA";
+	const std::string signing_input = h_b64 + "." + p_b64;
+	unsigned char mac[CryptoPP::SHA256::DIGESTSIZE];
+	CryptoPP::HMAC<CryptoPP::SHA256> hmac(secret.data(), secret.size());
+	hmac.Update(reinterpret_cast<const unsigned char *>(signing_input.data()),
+	            signing_input.size());
+	hmac.Final(mac);
+	const std::string sig = Base64UrlEncodeForTest(mac, sizeof(mac));
+	const std::string token = signing_input + "." + sig;
+	CJwt::VerifyResult r;
+	ASSERT_FALSE(auth.Verify(token, r));
+}
+
+
+// --- Depth-cap defence against unauthenticated stack-overflow -------
+//
+// picojson::parse recurses one stack frame per `{`/`[`. On musl (128
+// KiB stack) a few hundred levels crash the worker — and both Verify()
+// parse sites run BEFORE the MAC verdict, so an unauthenticated peer
+// can submit `Authorization: Bearer <crafted>` with deeply-nested
+// JSON and crash the daemon. The pre-parse opener-count cap (>32
+// rejects) blocks both sides in O(body length) with zero allocations.
+// Tests craft tokens past the cap, sign with the matching HMAC so
+// the MAC compare passes, then assert Verify() rejects.
+
+namespace {
+
+std::string DeeplyNested(const std::string &leaf, std::size_t levels)
+{
+	// {"a":{"a":...{"a":leaf}...}}  → levels openers.
+	std::string out;
+	out.reserve(levels * 6 + leaf.size() + levels);
+	for (std::size_t i = 0; i < levels; ++i) out += "{\"a\":";
+	out += leaf;
+	for (std::size_t i = 0; i < levels; ++i) out += "}";
+	return out;
+}
+
+}  // namespace
+
+
+TEST(Jwt, DeeplyNestedPayloadRejected)
+{
+	const auto secret = MakeSecret(0xA9);
+	CJwt auth(secret);
+	// 200 levels — well over the 32-opener cap but small enough that
+	// the test stays fast and doesn't itself risk a stack overflow.
+	const std::string token = CraftToken(
+		secret,
+		"{\"alg\":\"HS256\",\"typ\":\"JWT\"}",
+		DeeplyNested("1", 200));
+	CJwt::VerifyResult r;
+	ASSERT_FALSE(auth.Verify(token, r));
+}
+
+
+TEST(Jwt, DeeplyNestedHeaderRejected)
+{
+	const auto secret = MakeSecret(0xAB);
+	CJwt auth(secret);
+	const std::string token = CraftToken(
+		secret,
+		DeeplyNested("\"x\"", 200),
+		"{\"role\":\"admin\",\"exp\":9999999999,\"jti\":\"t\"}");
+	CJwt::VerifyResult r;
+	ASSERT_FALSE(auth.Verify(token, r));
+}
diff --git a/unittests/tests/PathPatternsTest.cpp b/unittests/tests/PathPatternsTest.cpp
new file mode 100644
index 0000000000..811fc3164f
--- /dev/null
+++ b/unittests/tests/PathPatternsTest.cpp
@@ -0,0 +1,286 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#include <muleunit/test.h>
+#include "PathPatterns.h"
+
+using namespace muleunit;
+using namespace web_api_path;
+
+
+DECLARE_SIMPLE(PathPatterns)
+
+
+// ----------------------------------------------------------------------
+// SplitPath
+// ----------------------------------------------------------------------
+
+TEST(PathPatterns, SplitPath_Empty)
+{
+	auto s = SplitPath("");
+	ASSERT_EQUALS(static_cast<size_t>(0), s.size());
+}
+
+TEST(PathPatterns, SplitPath_Root)
+{
+	// "/" parses to a single empty segment — distinguishable from "".
+	auto s = SplitPath("/");
+	ASSERT_EQUALS(static_cast<size_t>(1), s.size());
+	ASSERT_EQUALS(std::string(""), s[0]);
+}
+
+TEST(PathPatterns, SplitPath_Single)
+{
+	auto s = SplitPath("/version");
+	ASSERT_EQUALS(static_cast<size_t>(1), s.size());
+	ASSERT_EQUALS(std::string("version"), s[0]);
+}
+
+TEST(PathPatterns, SplitPath_Multiple)
+{
+	auto s = SplitPath("/downloads/abc/pause");
+	ASSERT_EQUALS(static_cast<size_t>(3), s.size());
+	ASSERT_EQUALS(std::string("downloads"), s[0]);
+	ASSERT_EQUALS(std::string("abc"),       s[1]);
+	ASSERT_EQUALS(std::string("pause"),     s[2]);
+}
+
+TEST(PathPatterns, SplitPath_TrailingSlash)
+{
+	// A trailing slash emits an empty trailing segment so the matcher
+	// can distinguish "/a/" from "/a".
+	auto s = SplitPath("/a/");
+	ASSERT_EQUALS(static_cast<size_t>(2), s.size());
+	ASSERT_EQUALS(std::string("a"), s[0]);
+	ASSERT_EQUALS(std::string(""), s[1]);
+}
+
+TEST(PathPatterns, SplitPath_NoLeadingSlash)
+{
+	// Absolute path is conventional, but the splitter doesn't require it.
+	auto s = SplitPath("a/b");
+	ASSERT_EQUALS(static_cast<size_t>(2), s.size());
+	ASSERT_EQUALS(std::string("a"), s[0]);
+	ASSERT_EQUALS(std::string("b"), s[1]);
+}
+
+
+// ----------------------------------------------------------------------
+// ParseQuery
+// ----------------------------------------------------------------------
+
+TEST(PathPatterns, ParseQuery_Empty)
+{
+	auto m = ParseQuery("");
+	ASSERT_EQUALS(static_cast<size_t>(0), m.size());
+}
+
+TEST(PathPatterns, ParseQuery_Single)
+{
+	auto m = ParseQuery("k=v");
+	ASSERT_EQUALS(static_cast<size_t>(1), m.size());
+	ASSERT_EQUALS(std::string("v"), m["k"]);
+}
+
+TEST(PathPatterns, ParseQuery_Multiple)
+{
+	auto m = ParseQuery("a=1&b=2&c=3");
+	ASSERT_EQUALS(static_cast<size_t>(3), m.size());
+	ASSERT_EQUALS(std::string("1"), m["a"]);
+	ASSERT_EQUALS(std::string("2"), m["b"]);
+	ASSERT_EQUALS(std::string("3"), m["c"]);
+}
+
+TEST(PathPatterns, ParseQuery_KeyWithoutValue)
+{
+	// "k" with no "=v" is parsed as key "k" with empty value (HTTP /
+	// HTML form convention).
+	auto m = ParseQuery("a&b=2");
+	ASSERT_EQUALS(static_cast<size_t>(2), m.size());
+	ASSERT_EQUALS(std::string(""), m["a"]);
+	ASSERT_EQUALS(std::string("2"), m["b"]);
+}
+
+TEST(PathPatterns, ParseQuery_EqualsInValue)
+{
+	// A `=` after the first one is part of the value, not a new
+	// key/value separator.
+	auto m = ParseQuery("expr=a=b");
+	ASSERT_EQUALS(std::string("a=b"), m["expr"]);
+}
+
+
+TEST(PathPatterns, ParseQuery_PercentDecode)
+{
+	// %20 in both keys and values; values are application/x-www-form-
+	// urlencoded so `+` decodes to space too.
+	auto m = ParseQuery("a%20b=c%3Dd&e=f+g");
+	ASSERT_EQUALS(std::string("c=d"), m["a b"]);
+	ASSERT_EQUALS(std::string("f g"), m["e"]);
+}
+
+
+TEST(PathPatterns, ParseQuery_MalformedPercentPassThrough)
+{
+	// A stray `%` with no two hex digits behind it passes through
+	// verbatim — we don't drop the character (would silently shift
+	// downstream parsing).
+	auto m = ParseQuery("k=ab%cz");
+	ASSERT_EQUALS(std::string("ab%cz"), m["k"]);
+	auto m2 = ParseQuery("k=trailing%");
+	ASSERT_EQUALS(std::string("trailing%"), m2["k"]);
+}
+
+
+TEST(PathPatterns, ParseQuery_PercentCaseInsensitive)
+{
+	// Both `%2F` and `%2f` decode to `/` per RFC 3986.
+	auto m = ParseQuery("a=foo%2Fbar&b=foo%2fbar");
+	ASSERT_EQUALS(std::string("foo/bar"), m["a"]);
+	ASSERT_EQUALS(std::string("foo/bar"), m["b"]);
+}
+
+
+// ----------------------------------------------------------------------
+// ParsePattern
+// ----------------------------------------------------------------------
+
+TEST(PathPatterns, ParsePattern_LiteralOnly)
+{
+	RoutePattern p = ParsePattern("/version");
+	ASSERT_EQUALS(static_cast<size_t>(1), p.segments.size());
+	ASSERT_EQUALS(std::string("version"), p.segments[0]);
+	ASSERT_EQUALS(std::string(""), p.capture_names[0]);
+}
+
+TEST(PathPatterns, ParsePattern_SingleCapture)
+{
+	RoutePattern p = ParsePattern("/downloads/{hash}");
+	ASSERT_EQUALS(static_cast<size_t>(2), p.segments.size());
+	ASSERT_EQUALS(std::string("downloads"), p.segments[0]);
+	ASSERT_EQUALS(std::string("{hash}"),    p.segments[1]);
+	ASSERT_EQUALS(std::string(""),     p.capture_names[0]);
+	ASSERT_EQUALS(std::string("hash"), p.capture_names[1]);
+}
+
+TEST(PathPatterns, ParsePattern_CaptureMidPath)
+{
+	RoutePattern p = ParsePattern("/downloads/{hash}/pause");
+	ASSERT_EQUALS(static_cast<size_t>(3), p.segments.size());
+	ASSERT_EQUALS(std::string("hash"), p.capture_names[1]);
+	ASSERT_EQUALS(std::string(""),     p.capture_names[2]);
+}
+
+
+// ----------------------------------------------------------------------
+// Match
+// ----------------------------------------------------------------------
+
+TEST(PathPatterns, Match_Literal_OK)
+{
+	RoutePattern p = ParsePattern("/version");
+	std::map<std::string,std::string> caps;
+	ASSERT_TRUE(Match(p, SplitPath("/version"), caps));
+	ASSERT_EQUALS(static_cast<size_t>(0), caps.size());
+}
+
+TEST(PathPatterns, Match_Literal_Mismatch)
+{
+	RoutePattern p = ParsePattern("/version");
+	std::map<std::string,std::string> caps;
+	ASSERT_FALSE(Match(p, SplitPath("/status"), caps));
+}
+
+TEST(PathPatterns, Match_Literal_DifferentLength)
+{
+	RoutePattern p = ParsePattern("/a/b");
+	std::map<std::string,std::string> caps;
+	ASSERT_FALSE(Match(p, SplitPath("/a/b/c"), caps));
+	ASSERT_FALSE(Match(p, SplitPath("/a"),     caps));
+}
+
+TEST(PathPatterns, Match_Capture_Single)
+{
+	RoutePattern p = ParsePattern("/downloads/{hash}");
+	std::map<std::string,std::string> caps;
+	ASSERT_TRUE(Match(p, SplitPath("/downloads/31d6cfe0"), caps));
+	ASSERT_EQUALS(std::string("31d6cfe0"), caps["hash"]);
+}
+
+TEST(PathPatterns, Match_Capture_Mid)
+{
+	RoutePattern p = ParsePattern("/downloads/{hash}/pause");
+	std::map<std::string,std::string> caps;
+	ASSERT_TRUE(Match(p, SplitPath("/downloads/abc/pause"), caps));
+	ASSERT_EQUALS(std::string("abc"), caps["hash"]);
+}
+
+TEST(PathPatterns, Match_Capture_LengthMismatch)
+{
+	RoutePattern p = ParsePattern("/downloads/{hash}/pause");
+	std::map<std::string,std::string> caps;
+	ASSERT_FALSE(Match(p, SplitPath("/downloads/abc"), caps));
+	ASSERT_FALSE(Match(p, SplitPath("/downloads/abc/pause/extra"), caps));
+}
+
+
+// ----------------------------------------------------------------------
+// ShapeEqual
+// ----------------------------------------------------------------------
+
+TEST(PathPatterns, ShapeEqual_SamePattern)
+{
+	RoutePattern a = ParsePattern("/downloads/{hash}/pause");
+	RoutePattern b = ParsePattern("/downloads/{hash}/pause");
+	ASSERT_TRUE(ShapeEqual(a, b));
+}
+
+TEST(PathPatterns, ShapeEqual_DifferentCaptureName)
+{
+	// Two patterns differing only in capture name shape-collide.
+	RoutePattern a = ParsePattern("/downloads/{hash}/pause");
+	RoutePattern b = ParsePattern("/downloads/{id}/pause");
+	ASSERT_TRUE(ShapeEqual(a, b));
+}
+
+TEST(PathPatterns, ShapeEqual_DifferentLiteral)
+{
+	RoutePattern a = ParsePattern("/downloads/{hash}/pause");
+	RoutePattern b = ParsePattern("/downloads/{hash}/resume");
+	ASSERT_FALSE(ShapeEqual(a, b));
+}
+
+TEST(PathPatterns, ShapeEqual_CaptureVsLiteral)
+{
+	RoutePattern a = ParsePattern("/downloads/{x}");
+	RoutePattern b = ParsePattern("/downloads/all");
+	ASSERT_FALSE(ShapeEqual(a, b));
+}
+
+TEST(PathPatterns, ShapeEqual_DifferentLengths)
+{
+	RoutePattern a = ParsePattern("/a/b");
+	RoutePattern b = ParsePattern("/a/b/c");
+	ASSERT_FALSE(ShapeEqual(a, b));
+}
diff --git a/unittests/tests/RefresherTest.cpp b/unittests/tests/RefresherTest.cpp
new file mode 100644
index 0000000000..4729642cd6
--- /dev/null
+++ b/unittests/tests/RefresherTest.cpp
@@ -0,0 +1,733 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#include <muleunit/test.h>
+
+#include "Refresher.h"
+#include "State.h"
+
+#include "RLE.h"   // PartFileEncoderData for the rle_state arg
+
+#include <ec/cpp/ECPacket.h>
+#include <ec/cpp/ECTag.h>
+#include <ec/cpp/ECCodes.h>
+
+#include <cstdint>
+#include <map>
+
+
+using namespace muleunit;
+using namespace webapi;
+
+
+DECLARE_SIMPLE(Refresher)
+
+
+// ----------------------------------------------------------------------
+// EC_TAG_FILE_REMOVED — INC-protocol deletion marker. With GET_UPDATE
+// + EC_DETAIL_INC_UPDATE the marker arrives in the consolidated response
+// packet. Both ApplyGetUpdateToDownloads and ApplyGetUpdateToShared
+// react to it (one will be a no-op for any given ECID since the
+// server-side encoder map is unified across both surfaces, but the
+// dispatch is per-walker).
+// ----------------------------------------------------------------------
+
+TEST(Refresher, FileRemovedErasesFromDownloads)
+{
+	// Pre-seed two downloads in the cache.
+	FileMap cache;
+	{
+		FileSnapshot d;
+		d.ecid = 42;
+		d.hash = "aaaa0000aaaa0000aaaa0000aaaa0000";
+		d.name = "doomed.iso";
+		cache.emplace(42, d);
+	}
+	{
+		FileSnapshot d;
+		d.ecid = 99;
+		d.hash = "bbbb1111bbbb1111bbbb1111bbbb1111";
+		d.name = "survivor.iso";
+		cache.emplace(99, d);
+	}
+
+	// Craft a GET_UPDATE response that contains a single
+	// EC_TAG_FILE_REMOVED marker pointing at ECID 42.
+	// The response packet's op code is what amuled emits per
+	// ExternalConn.cpp:874 (EC_OP_SHARED_FILES); the walker doesn't
+	// care, it iterates child tags.
+	CECPacket resp(EC_OP_SHARED_FILES);
+	resp.AddTag(CECTag(EC_TAG_FILE_REMOVED, static_cast<std::uint32_t>(42)));
+
+	std::map<std::uint32_t, PartFileEncoderData> rle_state;
+	ApplyGetUpdateToDownloads(&resp, cache, rle_state);
+
+	// Doomed download is gone.
+	ASSERT_TRUE(cache.find(42) == cache.end());
+	// Survivor is untouched — INC protocol uses explicit deletion
+	// markers, never "absence implies removed".
+	ASSERT_TRUE(cache.find(99) != cache.end());
+	ASSERT_EQUALS(std::string("survivor.iso"), cache.find(99)->second.name);
+}
+
+
+TEST(Refresher, FileRemovedErasesFromShared)
+{
+	// Symmetric to FileRemovedErasesFromDownloads. The server-side
+	// encoder map is unified across partfiles + sharedfiles, so a
+	// FILE_REMOVED marker could target an ECID in either cache.
+	// ApplyGetUpdateToShared evicts unconditionally; the eventual
+	// cross-walker call in RefresherTick has both walkers fire on
+	// the same response so the right cache loses the entry.
+	FileMap cache;
+	{
+		FileSnapshot s;
+		s.ecid = 33;
+		s.hash = "1111aaaa1111aaaa1111aaaa1111aaaa";
+		s.name = "shared-doomed.iso";
+		cache.emplace(33, s);
+	}
+
+	CECPacket resp(EC_OP_SHARED_FILES);
+	resp.AddTag(CECTag(EC_TAG_FILE_REMOVED, static_cast<std::uint32_t>(33)));
+
+	ApplyGetUpdateToShared(&resp, cache);
+
+	ASSERT_TRUE(cache.find(33) == cache.end());
+	ASSERT_TRUE(cache.empty());
+}
+
+
+TEST(Refresher, FileRemovedForUnknownEcidIsNoOp)
+{
+	// Cache contains a single known download.
+	FileMap cache;
+	{
+		FileSnapshot d;
+		d.ecid = 7;
+		d.hash = "cccc2222cccc2222cccc2222cccc2222";
+		d.name = "kept.iso";
+		cache.emplace(7, d);
+	}
+
+	// Server emits a stale removal marker for ECID 9999 we've never
+	// seen (race: server-side gen bumped between the two lookups).
+	// Erasing a missing key must be a no-op.
+	CECPacket resp(EC_OP_SHARED_FILES);
+	resp.AddTag(CECTag(EC_TAG_FILE_REMOVED, static_cast<std::uint32_t>(9999)));
+
+	std::map<std::uint32_t, PartFileEncoderData> rle_state;
+	ApplyGetUpdateToDownloads(&resp, cache, rle_state);
+
+	ASSERT_EQUALS(static_cast<size_t>(1), cache.size());
+	ASSERT_TRUE(cache.find(7) != cache.end());
+	ASSERT_EQUALS(std::string("kept.iso"), cache.find(7)->second.name);
+}
+
+
+// ----------------------------------------------------------------------
+// Empty response (no churn since the last tick) — INC protocol's
+// silent-skip semantics. Downloads + shared caches stay intact.
+// ----------------------------------------------------------------------
+
+TEST(Refresher, EmptyResponseLeavesCachesIntact)
+{
+	FileMap downloads;
+	{
+		FileSnapshot d;
+		d.ecid = 1;
+		d.name = "alpha";
+		downloads.emplace(1, d);
+	}
+	FileMap shared;
+	{
+		FileSnapshot s;
+		s.ecid = 2;
+		s.name = "beta";
+		shared.emplace(2, s);
+	}
+
+	CECPacket resp(EC_OP_SHARED_FILES);
+	std::map<std::uint32_t, PartFileEncoderData> rle_state;
+	ApplyGetUpdateToDownloads(&resp, downloads, rle_state);
+	ApplyGetUpdateToShared(&resp, shared);
+
+	// INC protocol: empty response means "no changes since last tick".
+	// Cache stays intact — no bulk-delete fallback needed.
+	ASSERT_EQUALS(static_cast<size_t>(1), downloads.size());
+	ASSERT_EQUALS(static_cast<size_t>(1), shared.size());
+}
+
+
+// ----------------------------------------------------------------------
+// Mixed top-level dispatch — one GET_UPDATE response carries both
+// EC_TAG_PARTFILE and EC_TAG_KNOWNFILE at the same level. The two
+// walkers must each consume only their own tag type without
+// cross-contaminating the other cache.
+// ----------------------------------------------------------------------
+
+TEST(Refresher, MixedTopLevelDispatchedByTagName)
+{
+	FileMap downloads;
+	FileMap shared;
+	std::map<std::uint32_t, PartFileEncoderData> rle_state;
+
+	CECPacket resp(EC_OP_SHARED_FILES);
+	// One partfile (ECID 10) — should land in downloads only.
+	resp.AddTag(CECTag(EC_TAG_PARTFILE,  static_cast<std::uint32_t>(10)));
+	// One sharedfile (ECID 20) — should land in shared only.
+	resp.AddTag(CECTag(EC_TAG_KNOWNFILE, static_cast<std::uint32_t>(20)));
+	// A FILE_REMOVED marker (ECID 99) — erases from both walkers'
+	// caches; since neither was pre-seeded, it's a no-op for both.
+	resp.AddTag(CECTag(EC_TAG_FILE_REMOVED, static_cast<std::uint32_t>(99)));
+
+	ApplyGetUpdateToDownloads(&resp, downloads, rle_state);
+	ApplyGetUpdateToShared(&resp, shared);
+
+	// Downloads walker captured ECID 10 only — NOT ECID 20 (that
+	// belongs to shared) and NOT ECID 99 (that's the FILE_REMOVED).
+	ASSERT_EQUALS(static_cast<size_t>(1), downloads.size());
+	ASSERT_TRUE(downloads.find(10) != downloads.end());
+	ASSERT_TRUE(downloads.find(20) == downloads.end());
+
+	// Shared walker captured ECID 20 only.
+	ASSERT_EQUALS(static_cast<size_t>(1), shared.size());
+	ASSERT_TRUE(shared.find(20) != shared.end());
+	ASSERT_TRUE(shared.find(10) == shared.end());
+}
+
+
+// ----------------------------------------------------------------------
+// Shared partfile dispatch — amuled's /shared surface is the union
+// of completed knownfiles AND partfiles with `IsShared()=true`
+// (i.e. ≥1 chunk completed → uploadable). GET_UPDATE ships partfiles
+// as EC_TAG_PARTFILE with a child `EC_TAG_PARTFILE_SHARED` bool.
+// The shared walker has to consume both top-level tag types and gate
+// partfile inclusion on the flag.
+// ----------------------------------------------------------------------
+
+TEST(Refresher, SharedPartfileWithFlagTrueLandsInShared)
+{
+	FileMap cache;
+	CECPacket resp(EC_OP_SHARED_FILES);
+	{
+		CECTag pf(EC_TAG_PARTFILE, static_cast<std::uint32_t>(50));
+		// IsShared==true: this partfile has ≥1 chunk and is currently
+		// uploadable. The shared walker should pick it up.
+		pf.AddTag(CECTag(EC_TAG_PARTFILE_SHARED, static_cast<std::uint8_t>(1)));
+		resp.AddTag(pf);
+	}
+
+	// PARTFILE_HASH is CValueMap-suppressed on the partfile-to-shared
+	// transition tick — supply identity via the downloads-cache fallback,
+	// which is how the live code recovers it.
+	std::map<std::uint32_t, std::pair<std::string, std::string>> fallback;
+	fallback[50] = std::make_pair(
+		std::string("aaaa3333aaaa3333aaaa3333aaaa3333"),
+		std::string("shared-test.iso"));
+	ApplyGetUpdateToShared(&resp, cache);
+
+	ASSERT_EQUALS(static_cast<size_t>(1), cache.size());
+	ASSERT_TRUE(cache.find(50) != cache.end());
+	ASSERT_EQUALS(static_cast<std::uint32_t>(50), cache.find(50)->second.ecid);
+}
+
+
+TEST(Refresher, UnsharedPartfileSkippedFromShared)
+{
+	// PARTFILE arrives with EC_TAG_PARTFILE_SHARED=false. The
+	// shared walker must NOT insert it — the file is in the download
+	// queue but has zero chunks completed, so no peer can request it.
+	FileMap cache;
+	CECPacket resp(EC_OP_SHARED_FILES);
+	{
+		CECTag pf(EC_TAG_PARTFILE, static_cast<std::uint32_t>(60));
+		pf.AddTag(CECTag(EC_TAG_PARTFILE_SHARED, static_cast<std::uint8_t>(0)));
+		resp.AddTag(pf);
+	}
+
+	ApplyGetUpdateToShared(&resp, cache);
+
+	ASSERT_TRUE(cache.empty());
+}
+
+
+TEST(Refresher, SharedPartfileTransitionsOutClearsSharedRole)
+{
+	// Pre-seed a shared partfile in cache (was sharing on previous
+	// ticks). Now the operator paused / stopped it: the next tick
+	// emits EC_TAG_PARTFILE_SHARED=false. The walker must clear the
+	// is_shared role (and reset the shared sub-block so /shared can't
+	// surface stale upload stats). The entry itself stays in the
+	// unified map — entity-level eviction is FILE_REMOVED's job.
+	FileMap cache;
+	{
+		FileSnapshot s;
+		s.ecid = 70;
+		s.hash = "dddd4444dddd4444dddd4444dddd4444";
+		s.name = "was-sharing.iso";
+		s.is_shared = true;
+		s.shared.xfer_session = 99;  // stale stat to verify the reset
+		cache.emplace(70, s);
+	}
+	CECPacket resp(EC_OP_SHARED_FILES);
+	{
+		CECTag pf(EC_TAG_PARTFILE, static_cast<std::uint32_t>(70));
+		pf.AddTag(CECTag(EC_TAG_PARTFILE_SHARED, static_cast<std::uint8_t>(0)));
+		resp.AddTag(pf);
+	}
+
+	ApplyGetUpdateToShared(&resp, cache);
+
+	ASSERT_TRUE(cache.find(70) != cache.end());
+	ASSERT_TRUE(!cache.find(70)->second.is_shared);
+	// Stale upload stats from the prior sharing period must be cleared
+	// so /shared can never re-surface them.
+	ASSERT_EQUALS(static_cast<std::uint64_t>(0),
+	              cache.find(70)->second.shared.xfer_session);
+}
+
+
+TEST(Refresher, SuppressedSharedFlagPreservesCachedPartfile)
+{
+	// CValueMap suppresses the EC_TAG_PARTFILE_SHARED tag when the
+	// value matches the previous frame. For a cached partfile that
+	// was previously shared, the absence of the flag means "still
+	// shared" — the walker must keep it and apply stat deltas.
+	FileMap cache;
+	{
+		FileSnapshot s;
+		s.ecid = 80;
+		s.hash = "eeee5555eeee5555eeee5555eeee5555";
+		s.name = "still-sharing.iso";
+		cache.emplace(80, s);
+	}
+	CECPacket resp(EC_OP_SHARED_FILES);
+	// PARTFILE with no EC_TAG_PARTFILE_SHARED child — flag suppressed.
+	resp.AddTag(CECTag(EC_TAG_PARTFILE, static_cast<std::uint32_t>(80)));
+
+	ApplyGetUpdateToShared(&resp, cache);
+
+	ASSERT_TRUE(cache.find(80) != cache.end());
+	ASSERT_EQUALS(std::string("still-sharing.iso"), cache.find(80)->second.name);
+}
+
+
+TEST(Refresher, SuppressedSharedFlagSkipsUnknownPartfile)
+{
+	// Mirror of the previous test: a PARTFILE with the SHARED flag
+	// suppressed AND no prior cache entry means "we have no signal
+	// that this is shared." Don't insert blindly — wait for the next
+	// tick that flips the state to emit the flag.
+	FileMap cache;
+	CECPacket resp(EC_OP_SHARED_FILES);
+	resp.AddTag(CECTag(EC_TAG_PARTFILE, static_cast<std::uint32_t>(90)));
+
+	ApplyGetUpdateToShared(&resp, cache);
+
+	ASSERT_TRUE(cache.empty());
+}
+
+
+// ----------------------------------------------------------------------
+// New ECID arrives in one tick with identity baked in — the whole
+// point of the GET_UPDATE consolidation. INC_UPDATE doesn't hit the
+// EC_DETAIL_UPDATE early-return at ECSpecialCoreTags.cpp:244-246, so
+// HASH / NAME / SIZE are shipped on first encounter; no second
+// roundtrip needed.
+// ----------------------------------------------------------------------
+
+TEST(Refresher, NewPartfileInsertedInOneTick)
+{
+	FileMap cache;
+	std::map<std::uint32_t, PartFileEncoderData> rle_state;
+
+	// Craft a partfile tag with just the ECID. The walker dispatches
+	// on tag name, calls TagHashLower + MergePartFileTag — both of
+	// which gracefully tolerate an absent child set. After the
+	// walker runs, ECID 55 is in the cache with default-init fields.
+	// (In production a real CEC_PartFile_Tag at INC_UPDATE always
+	// carries the full identity child set; this test pins the bare-
+	// minimum insertion path.)
+	CECPacket resp(EC_OP_SHARED_FILES);
+	resp.AddTag(CECTag(EC_TAG_PARTFILE, static_cast<std::uint32_t>(55)));
+
+	ApplyGetUpdateToDownloads(&resp, cache, rle_state);
+
+	// The new ECID landed — no needed.
+	ASSERT_EQUALS(static_cast<size_t>(1), cache.size());
+	ASSERT_TRUE(cache.find(55) != cache.end());
+	ASSERT_EQUALS(static_cast<std::uint32_t>(55), cache.find(55)->second.ecid);
+}
+
+
+// ----------------------------------------------------------------------
+// /servers — GET_UPDATE wraps per-server tags in an EC_TAG_SERVER
+// container at top level. Walker iterates INTO the container and
+// merges per-ECID; cache entries not seen in the response get evicted
+// because the server side has no FILE_REMOVED equivalent for servers
+// (the container always carries the full current list).
+// ----------------------------------------------------------------------
+
+TEST(Refresher, ServersFromContainerMergesByEcid)
+{
+	std::map<std::uint32_t, ServerSnapshot> cache;
+	// Pre-seed an entry that should disappear: a server the operator
+	// removed from amuled between ticks (it won't show up in the new
+	// response's SERVER container).
+	{
+		ServerSnapshot s;
+		s.ecid = 9999;
+		s.name = "removed";
+		cache.emplace(9999, s);
+	}
+
+	// Build a SERVER container with one per-server child (ECID 42).
+	CECPacket resp(EC_OP_SHARED_FILES);
+	{
+		CECTag container(EC_TAG_SERVER, static_cast<std::uint32_t>(0));
+		// One per-server child tag inside the container — same
+		// EC_TAG_SERVER name (the walker disambiguates by depth, not
+		// by name). Minimum tags needed for the merge to populate
+		// the snapshot.
+		CECTag srv(EC_TAG_SERVER, static_cast<std::uint32_t>(42));
+		srv.AddTag(CECTag(EC_TAG_SERVER_USERS, static_cast<std::uint32_t>(1234)));
+		container.AddTag(srv);
+		resp.AddTag(container);
+	}
+
+	ApplyGetUpdateToServers(&resp, cache);
+
+	ASSERT_EQUALS(static_cast<size_t>(1), cache.size());
+	ASSERT_TRUE(cache.find(42)   != cache.end());
+	ASSERT_TRUE(cache.find(9999) == cache.end());   // evicted
+	ASSERT_EQUALS(static_cast<std::uint32_t>(1234), cache[42].users);
+}
+
+
+TEST(Refresher, ServersEmptyContainerEmptiesCache)
+{
+	std::map<std::uint32_t, ServerSnapshot> cache;
+	cache.emplace(1, ServerSnapshot{});
+	cache.emplace(2, ServerSnapshot{});
+
+	// Empty SERVER container (operator removed every server). Every
+	// pre-seeded entry is "not seen this tick" → evicted.
+	CECPacket resp(EC_OP_SHARED_FILES);
+	resp.AddTag(CECTag(EC_TAG_SERVER, static_cast<std::uint32_t>(0)));
+
+	ApplyGetUpdateToServers(&resp, cache);
+
+	ASSERT_TRUE(cache.empty());
+}
+
+
+TEST(Refresher, ServersNoContainerLeavesCacheAlone)
+{
+	// Defensive: if a response is missing the SERVER container
+	// entirely (which production amuled never does — it always
+	// emits the container even when empty), the walker leaves the
+	// cache untouched. Better than wiping on an unexpected wire
+	// shape.
+	std::map<std::uint32_t, ServerSnapshot> cache;
+	cache.emplace(7, ServerSnapshot{});
+
+	CECPacket resp(EC_OP_SHARED_FILES);
+	// No EC_TAG_SERVER container in the response.
+
+	ApplyGetUpdateToServers(&resp, cache);
+
+	ASSERT_EQUALS(static_cast<size_t>(1), cache.size());
+	ASSERT_TRUE(cache.find(7) != cache.end());
+}
+
+
+// ----------------------------------------------------------------------
+// RLE state map — cleaned up alongside the cache when a partfile
+// gets evicted via FILE_REMOVED. Without the cleanup, the decoder's
+// internal buffer (~200 KB per partfile on TB-class files) would
+// slowly leak.
+// ----------------------------------------------------------------------
+
+TEST(Refresher, RleStateErasedAlongsideFileRemoved)
+{
+	FileMap cache;
+	std::map<std::uint32_t, PartFileEncoderData> rle_state;
+	{
+		FileSnapshot d;
+		d.ecid = 77;
+		d.hash = "aaaa0000aaaa0000aaaa0000aaaa0000";
+		d.name = "doomed.iso";
+		cache.emplace(77, d);
+		// Simulate a previous tick having allocated a decoder for ECID 77.
+		rle_state.emplace(77, PartFileEncoderData{});
+	}
+
+	CECPacket resp(EC_OP_SHARED_FILES);
+	resp.AddTag(CECTag(EC_TAG_FILE_REMOVED, static_cast<std::uint32_t>(77)));
+
+	ApplyGetUpdateToDownloads(&resp, cache, rle_state);
+
+	ASSERT_TRUE(cache.find(77)     == cache.end());
+	ASSERT_TRUE(rle_state.find(77) == rle_state.end());
+}
+
+
+TEST(Refresher, RleStatePreservedForKnownEntryAcrossTick)
+{
+	// A partfile already in cache should KEEP its RLE state across a
+	// tick that brings no new info. The decoder relies on its buffer
+	// surviving from the prior tick.
+	FileMap cache;
+	std::map<std::uint32_t, PartFileEncoderData> rle_state;
+	{
+		FileSnapshot d;
+		d.ecid = 5;
+		d.hash = "bbbb1111bbbb1111bbbb1111bbbb1111";
+		d.name = "stable.iso";
+		cache.emplace(5, d);
+		rle_state.emplace(5, PartFileEncoderData{});
+	}
+
+	// A no-op response (no PARTFILE tags, no FILE_REMOVED). Nothing
+	// should churn.
+	CECPacket resp(EC_OP_SHARED_FILES);
+	ApplyGetUpdateToDownloads(&resp, cache, rle_state);
+
+	ASSERT_TRUE(cache.find(5)     != cache.end());
+	ASSERT_TRUE(rle_state.find(5) != rle_state.end());
+}
+
+
+// ----------------------------------------------------------------------
+// /stats/tree — recursive walk strips the root container and surfaces
+// its children at the top level. Crafted as a hand-built CECTag tree.
+// ----------------------------------------------------------------------
+
+TEST(Refresher, StatusDecodeCompleteOverridesStopped)
+{
+	// A completed download in amuled sits in `m_completedDownloads`
+	// with EC_TAG_PARTFILE_STOPPED set true. The decoder used to
+	// short-circuit on `stopped` and report "paused" — masking the
+	// PS_COMPLETE state from /downloads consumers (and breaking the
+	// status=="completed" filter). PS_COMPLETE (and
+	// PS_COMPLETING) must take priority over the stopped flag.
+	//
+	// PS_COMPLETE = 9 (Constants.h). Crafting a partfile tag with
+	// PS_STATUS=9 + STOPPED=true exercises the merge path through
+	// ApplyGetUpdateToDownloads.
+	FileMap cache;
+	std::map<std::uint32_t, PartFileEncoderData> rle_state;
+
+	CECPacket resp(EC_OP_SHARED_FILES);
+	{
+		CECTag pf(EC_TAG_PARTFILE, static_cast<std::uint32_t>(101));
+		pf.AddTag(CECTag(EC_TAG_PARTFILE_STATUS,
+			static_cast<std::uint8_t>(9 /* PS_COMPLETE */)));
+		pf.AddTag(CECTag(EC_TAG_PARTFILE_STOPPED, true));
+		resp.AddTag(pf);
+	}
+
+	ApplyGetUpdateToDownloads(&resp, cache, rle_state);
+
+	ASSERT_TRUE(cache.find(101) != cache.end());
+	ASSERT_EQUALS(std::string("completed"), cache.find(101)->second.download.status);
+}
+
+
+TEST(Refresher, StatusDecodeCompletingOverridesStopped)
+{
+	// Same shape, PS_COMPLETING (=8) takes priority over stopped too
+	// — covers the in-flight finalization race where the cache is
+	// being moved from m_filelist to m_completedDownloads.
+	FileMap cache;
+	std::map<std::uint32_t, PartFileEncoderData> rle_state;
+
+	CECPacket resp(EC_OP_SHARED_FILES);
+	{
+		CECTag pf(EC_TAG_PARTFILE, static_cast<std::uint32_t>(102));
+		pf.AddTag(CECTag(EC_TAG_PARTFILE_STATUS,
+			static_cast<std::uint8_t>(8 /* PS_COMPLETING */)));
+		pf.AddTag(CECTag(EC_TAG_PARTFILE_STOPPED, true));
+		resp.AddTag(pf);
+	}
+
+	ApplyGetUpdateToDownloads(&resp, cache, rle_state);
+	ASSERT_TRUE(cache.find(102) != cache.end());
+	ASSERT_EQUALS(std::string("completing"), cache.find(102)->second.download.status);
+}
+
+
+TEST(Refresher, StatusDecodeStoppedNonCompleteStaysPaused)
+{
+	// Sanity check the other direction: a download that's stopped
+	// but NOT yet completed (user paused mid-transfer) must still
+	// report "paused" — the fix only carves out
+	// PS_COMPLETE/PS_COMPLETING.
+	FileMap cache;
+	std::map<std::uint32_t, PartFileEncoderData> rle_state;
+
+	CECPacket resp(EC_OP_SHARED_FILES);
+	{
+		CECTag pf(EC_TAG_PARTFILE, static_cast<std::uint32_t>(103));
+		// PS_READY = 0 (transferring). User paused it.
+		pf.AddTag(CECTag(EC_TAG_PARTFILE_STATUS,
+			static_cast<std::uint8_t>(0)));
+		pf.AddTag(CECTag(EC_TAG_PARTFILE_STOPPED, true));
+		resp.AddTag(pf);
+	}
+
+	ApplyGetUpdateToDownloads(&resp, cache, rle_state);
+	ASSERT_TRUE(cache.find(103) != cache.end());
+	ASSERT_EQUALS(std::string("paused"), cache.find(103)->second.download.status);
+}
+
+
+TEST(Refresher, ParseStatsTreeStripsRootAndRecursesChildren)
+{
+	// Build:
+	//  root
+	//  ├── Transfer
+	//  │   └── Total bytes ...
+	//  └── Connection
+	CECPacket resp(EC_OP_STATSTREE);
+	CECTag root(EC_TAG_STATTREE_NODE, wxString("root-container-label-discarded"));
+	{
+		CECTag transfer(EC_TAG_STATTREE_NODE, wxString("Transfer"));
+		{
+			CECTag total(EC_TAG_STATTREE_NODE,
+				wxString("Total bytes transferred: 12.3 GiB"));
+			transfer.AddTag(total);
+		}
+		root.AddTag(transfer);
+	}
+	{
+		CECTag conn(EC_TAG_STATTREE_NODE, wxString("Connection"));
+		root.AddTag(conn);
+	}
+	resp.AddTag(root);
+
+	StatsTreeNode out;
+	ParseStatsTreeFromPacket(&resp, out);
+
+	// The root container itself is discarded; we expose its 2 children
+	// (Transfer + Connection) as top-level nodes.
+	ASSERT_TRUE(out.label.empty());
+	ASSERT_EQUALS(static_cast<size_t>(2),                 out.children.size());
+	// Transfer subtree.
+	ASSERT_EQUALS(std::string("Transfer"),                out.children[0].label);
+	ASSERT_EQUALS(static_cast<size_t>(1),                 out.children[0].children.size());
+	ASSERT_EQUALS(std::string("Total bytes transferred: 12.3 GiB"),
+	              out.children[0].children[0].label);
+	// Connection is a leaf at this depth.
+	ASSERT_EQUALS(std::string("Connection"),              out.children[1].label);
+	ASSERT_EQUALS(static_cast<size_t>(0),                 out.children[1].children.size());
+}
+
+
+
+
+// ----------------------------------------------------------------------
+// AdvanceSearchProgress — maps EC_TAG_SEARCH_LIFECYCLE_STATE +
+// EC_TAG_SEARCH_LIFECYCLE_PERCENT into (percent, complete, active).
+// Trusts the daemon's flags; the percent is the daemon's unified 0..100
+// for every kind (global = real, Kad = cosmetic ramp), so amuleapi no
+// longer masks it per-kind — it just passes it through and clamps.
+// ----------------------------------------------------------------------
+
+namespace {
+
+webapi::SearchProgressSnapshot MakeActive(const std::string &kind)
+{
+	webapi::SearchProgressSnapshot s;
+	s.active = true;
+	s.kind   = kind;
+	return s;
+}
+
+constexpr std::uint32_t LIFECYCLE_IDLE     = 0;
+constexpr std::uint32_t LIFECYCLE_RUNNING  = 1;
+constexpr std::uint32_t LIFECYCLE_FINISHED = 2;
+
+}  // namespace
+
+
+TEST(Refresher, SearchProgressRunningCarriesPercentForGlobal)
+{
+	using webapi::AdvanceSearchProgress;
+	webapi::SearchProgressSnapshot s = MakeActive("global");
+	s = AdvanceSearchProgress(s, LIFECYCLE_RUNNING, /*pct=*/42);
+	ASSERT_TRUE(s.active);
+	ASSERT_TRUE(!s.complete);
+	ASSERT_EQUALS(static_cast<uint32_t>(42), s.percent);
+}
+
+
+TEST(Refresher, SearchProgressRunningPassesThroughKadRamp)
+{
+	using webapi::AdvanceSearchProgress;
+	webapi::SearchProgressSnapshot s = MakeActive("kad");
+	// The daemon synthesises a cosmetic time-ramp for Kad and ships it in
+	// EC_TAG_SEARCH_LIFECYCLE_PERCENT, so amuleapi no longer masks Kad to
+	// 0 — it passes the daemon value straight through.
+	s = AdvanceSearchProgress(s, LIFECYCLE_RUNNING, /*pct=*/37);
+	ASSERT_TRUE(s.active);
+	ASSERT_EQUALS(static_cast<uint32_t>(37), s.percent);
+}
+
+
+TEST(Refresher, SearchProgressRunningClampsPercentAbove100)
+{
+	using webapi::AdvanceSearchProgress;
+	webapi::SearchProgressSnapshot s = MakeActive("global");
+	// The daemon's percent tag is 0..100, but stay defensive: any value
+	// above 100 is clamped rather than surfaced raw to consumers.
+	s = AdvanceSearchProgress(s, LIFECYCLE_RUNNING, /*pct=*/250);
+	ASSERT_TRUE(s.active);
+	ASSERT_EQUALS(static_cast<uint32_t>(100), s.percent);
+}
+
+
+TEST(Refresher, SearchProgressFinishedSetsComplete)
+{
+	using webapi::AdvanceSearchProgress;
+	webapi::SearchProgressSnapshot s = MakeActive("global");
+	s = AdvanceSearchProgress(s, LIFECYCLE_FINISHED, /*pct=*/0);
+	ASSERT_TRUE(!s.active);
+	ASSERT_TRUE(s.complete);
+	ASSERT_EQUALS(static_cast<uint32_t>(100), s.percent);
+}
+
+
+TEST(Refresher, SearchProgressIdleZeroesOutGracefully)
+{
+	using webapi::AdvanceSearchProgress;
+	webapi::SearchProgressSnapshot s = MakeActive("kad");
+	// Refresher shouldn't call us with state=IDLE (it gates on active
+	// being true on entry), but stay defensive: flip both flags off.
+	s = AdvanceSearchProgress(s, LIFECYCLE_IDLE, /*pct=*/0);
+	ASSERT_TRUE(!s.active);
+	ASSERT_TRUE(!s.complete);
+	ASSERT_EQUALS(static_cast<uint32_t>(0), s.percent);
+}
diff --git a/unittests/tests/StateTest.cpp b/unittests/tests/StateTest.cpp
new file mode 100644
index 0000000000..6667b20dfb
--- /dev/null
+++ b/unittests/tests/StateTest.cpp
@@ -0,0 +1,576 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// Any parts of this program derived from the xMule, lMule or eMule project,
+// or contributed by third-party developers are copyrighted by their
+// respective authors.
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+//
+
+#include <muleunit/test.h>
+
+#include "State.h"
+
+#include <atomic>
+#include <chrono>
+#include <cstdint>
+#include <map>
+#include <thread>
+#include <vector>
+
+
+using namespace muleunit;
+using namespace webapi;
+
+
+DECLARE_SIMPLE(State)
+
+
+TEST(State, FreshHasNoSnapshot)
+{
+	CState s;
+	ASSERT_FALSE(s.HasFirstSnapshot());
+	ASSERT_FALSE(s.EcConnected());
+	ASSERT_EQUALS(static_cast<std::time_t>(0), s.SnapshotAt());
+}
+
+
+TEST(State, MarkTickSuccessFlagsFreshness)
+{
+	CState s;
+	const std::time_t before = std::time(nullptr);
+	s.MarkTickSuccess();
+	const std::time_t after = std::time(nullptr);
+
+	ASSERT_TRUE(s.HasFirstSnapshot());
+	ASSERT_TRUE(s.EcConnected());
+	ASSERT_TRUE(s.SnapshotAt() >= before);
+	ASSERT_TRUE(s.SnapshotAt() <= after);
+}
+
+
+TEST(State, MarkTickFailurePreservesSnapshotAt)
+{
+	CState s;
+	s.MarkTickSuccess();
+	const std::time_t first_snapshot_at = s.SnapshotAt();
+
+	// Sleep a beat so a "snapshot_at = now" regression on
+	// MarkTickFailure would visibly change the value.
+	std::this_thread::sleep_for(std::chrono::milliseconds(1100));
+
+	s.MarkTickFailure();
+	ASSERT_FALSE(s.EcConnected());
+	// HasFirstSnapshot stays true — we have stale data, but data nonetheless.
+	ASSERT_TRUE(s.HasFirstSnapshot());
+	ASSERT_EQUALS(first_snapshot_at, s.SnapshotAt());
+}
+
+
+TEST(State, WriteStatusRoundtrip)
+{
+	CState s;
+	StatusSnapshot in;
+	in.ed2k_state     = "connected";
+	in.kad_state      = "connecting";
+	in.ed2k_lowid     = true;
+	in.kad_firewalled = false;
+	in.server_name    = "Some Server";
+	in.server_ip      = "192.0.2.42";
+	in.server_port    = 4242;
+	in.download_bps   = 12345;
+	in.upload_bps     = 6789;
+	in.ul_queue_len   = 3;
+	in.total_src_count = 17;
+	s.WriteStatus(in);
+
+	const StatusSnapshot out = s.Status();
+	ASSERT_EQUALS(std::string("connected"),  out.ed2k_state);
+	ASSERT_EQUALS(std::string("connecting"), out.kad_state);
+	ASSERT_TRUE (out.ed2k_lowid);
+	ASSERT_FALSE(out.kad_firewalled);
+	ASSERT_EQUALS(std::string("Some Server"), out.server_name);
+	ASSERT_EQUALS(std::string("192.0.2.42"),  out.server_ip);
+	ASSERT_EQUALS(static_cast<std::uint32_t>(4242),  out.server_port);
+	ASSERT_EQUALS(static_cast<std::uint64_t>(12345), out.download_bps);
+	ASSERT_EQUALS(static_cast<std::uint64_t>(6789),  out.upload_bps);
+	ASSERT_EQUALS(static_cast<std::uint32_t>(3),  out.ul_queue_len);
+	ASSERT_EQUALS(static_cast<std::uint32_t>(17), out.total_src_count);
+}
+
+
+TEST(State, MutateDownloadsRoundtripAndFind)
+{
+	CState s;
+	s.MutateDownloads([](FileMap &cache) {
+		FileSnapshot a;
+		a.ecid = 100;
+		a.hash = "aaaa0000aaaa0000aaaa0000aaaa0000";
+		a.name = "foo.iso";
+		a.size = 1000;
+		a.is_downloading = true;
+		a.download.size_done = 250;
+		a.priority = "high";
+		a.download.status   = "downloading";
+		a.download.percent  = 25.0;
+		cache.emplace(a.ecid, a);
+
+		FileSnapshot b;
+		b.ecid = 200;
+		b.hash = "bbbb1111bbbb1111bbbb1111bbbb1111";
+		b.name = "bar.iso";
+		b.is_downloading = true;
+		cache.emplace(b.ecid, b);
+	});
+
+	// Both entries should be present in the vector view. Order is
+	// unordered_map-bucket-defined (FileMap drops std::map's ECID
+	// ordering), so look entries up by ECID instead of position.
+	const auto out = s.Downloads();
+	ASSERT_EQUALS(static_cast<size_t>(2), out.size());
+	std::string foo_name, bar_name;
+	for (const auto &f : out) {
+		if (f.ecid == 100) foo_name = f.name;
+		if (f.ecid == 200) bar_name = f.name;
+	}
+	ASSERT_EQUALS(std::string("foo.iso"), foo_name);
+	ASSERT_EQUALS(std::string("bar.iso"), bar_name);
+
+	// Hash lookup goes through FindDownload's linear scan; both hits
+	// and misses must come back correctly.
+	FileSnapshot found;
+	ASSERT_TRUE(s.FindDownload("bbbb1111bbbb1111bbbb1111bbbb1111", found));
+	ASSERT_EQUALS(std::string("bar.iso"), found.name);
+	ASSERT_EQUALS(static_cast<std::uint32_t>(200), found.ecid);
+
+	FileSnapshot miss;
+	ASSERT_FALSE(s.FindDownload("0000000000000000000000000000000c", miss));
+}
+
+
+TEST(State, MutateDownloadsDecodedRleFieldsRoundtrip)
+{
+	// `decoded_gaps` + `decoded_part_sources` are populated by the
+	// refresher's stateful RLE decoder pass. CState just
+	// stores and surfaces them; this test pins that the per-part
+	// arrays survive the MutateDownloads → Downloads()/FindDownload
+	// roundtrip with element-level fidelity. Regression would manifest
+	// as `progress.parts` being empty or wrong-sized on the wire.
+	CState s;
+	s.MutateDownloads([](FileMap &cache) {
+		FileSnapshot a;
+		a.ecid = 42;
+		a.hash = "dddd3333dddd3333dddd3333dddd3333";
+		a.name = "with-rle.iso";
+		a.size = 9728000ull * 3;   // exactly 3 parts
+		a.is_downloading = true;
+		// One gap covering byte ranges 100..200 and 9728000..9800000:
+		// the first lies entirely in part 0, the second entirely in
+		// part 1.
+		a.download.decoded_gaps        = {100ull, 200ull, 9728000ull, 9800000ull};
+		// Three parts with source counts [5, 0, 7].
+		a.download.decoded_part_sources = {5, 0, 7};
+		cache.emplace(a.ecid, a);
+	});
+
+	const auto out = s.Downloads();
+	ASSERT_EQUALS(static_cast<size_t>(1), out.size());
+	ASSERT_EQUALS(static_cast<size_t>(4), out[0].download.decoded_gaps.size());
+	ASSERT_EQUALS(static_cast<std::uint64_t>(100),       out[0].download.decoded_gaps[0]);
+	ASSERT_EQUALS(static_cast<std::uint64_t>(200),       out[0].download.decoded_gaps[1]);
+	ASSERT_EQUALS(static_cast<std::uint64_t>(9728000),   out[0].download.decoded_gaps[2]);
+	ASSERT_EQUALS(static_cast<std::uint64_t>(9800000),   out[0].download.decoded_gaps[3]);
+	ASSERT_EQUALS(static_cast<size_t>(3), out[0].download.decoded_part_sources.size());
+	ASSERT_EQUALS(static_cast<std::uint16_t>(5), out[0].download.decoded_part_sources[0]);
+	ASSERT_EQUALS(static_cast<std::uint16_t>(0), out[0].download.decoded_part_sources[1]);
+	ASSERT_EQUALS(static_cast<std::uint16_t>(7), out[0].download.decoded_part_sources[2]);
+
+	// FindDownload returns the same surface (used by the detail
+	// endpoint, which is the only path that emits progress.parts).
+	FileSnapshot via_find;
+	ASSERT_TRUE(s.FindDownload("dddd3333dddd3333dddd3333dddd3333", via_find));
+	ASSERT_EQUALS(static_cast<size_t>(4), via_find.download.decoded_gaps.size());
+	ASSERT_EQUALS(static_cast<size_t>(3), via_find.download.decoded_part_sources.size());
+	ASSERT_EQUALS(static_cast<std::uint16_t>(7), via_find.download.decoded_part_sources[2]);
+}
+
+
+TEST(State, MutateClientsAndSharedRoundtrip)
+{
+	CState s;
+	// m_clients is the unified peer cache (all upload_state
+	// values). /clients endpoint surfaces the full set; consumers
+	// filter by role on their side.
+	s.MutateClients([](std::map<std::uint32_t, ClientSnapshot> &cache) {
+		ClientSnapshot c;
+		c.ecid = 10;
+		c.client_name = "peer-1";
+		c.upload_state = "uploading";
+		c.upload_speed_bps = 1234;
+		cache.emplace(c.ecid, c);
+	});
+	ASSERT_EQUALS(static_cast<size_t>(1), s.Clients().size());
+	ASSERT_EQUALS(std::string("peer-1"), s.Clients()[0].client_name);
+	ASSERT_EQUALS(std::string("uploading"), s.Clients()[0].upload_state);
+
+	s.MutateShared([](FileMap &cache) {
+		FileSnapshot x;
+		x.ecid = 20;
+		x.hash = "ffff2222ffff2222ffff2222ffff2222";
+		x.name = "shared.iso";
+		x.size = 4096;
+		x.is_shared = true;
+		x.priority = "normal";
+		cache.emplace(x.ecid, x);
+	});
+	ASSERT_EQUALS(static_cast<size_t>(1), s.Shared().size());
+	ASSERT_EQUALS(std::string("shared.iso"), s.Shared()[0].name);
+}
+
+
+TEST(State, WriteKadAndPreferencesRoundtrip)
+{
+	CState s;
+
+	KadSnapshot k;
+	k.state = "connected";
+	k.users = 12345;
+	k.firewalled = true;
+	k.ip = "1.2.3.4";
+	s.WriteKad(k);
+
+	PreferencesSnapshot p;
+	p.nickname = "tester";
+	p.user_hash = "deadbeefdeadbeefdeadbeefdeadbeef";
+	p.tcp_port = 4662;
+	p.udp_port = 4672;
+	p.network_ed2k = true;
+	s.WritePreferences(p);
+
+	std::vector<CategorySnapshot> cats;
+	{
+		CategorySnapshot c;
+		c.index = 0;
+		c.name = "All";
+		c.priority = "auto";
+		cats.push_back(c);
+	}
+	{
+		CategorySnapshot c;
+		c.index = 1;
+		c.name = "Movies";
+		c.path = "/tmp/movies";
+		c.priority = "high";
+		cats.push_back(c);
+	}
+	s.WriteCategories(cats);
+
+	const auto k_out = s.Kad();
+	ASSERT_EQUALS(std::string("connected"), k_out.state);
+	ASSERT_EQUALS(static_cast<std::uint32_t>(12345), k_out.users);
+	ASSERT_TRUE(k_out.firewalled);
+
+	const auto p_out = s.Preferences();
+	ASSERT_EQUALS(std::string("tester"), p_out.nickname);
+	ASSERT_EQUALS(static_cast<std::uint16_t>(4662), p_out.tcp_port);
+	ASSERT_TRUE(p_out.network_ed2k);
+	ASSERT_FALSE(p_out.network_kad);
+
+	const auto c_out = s.Categories();
+	ASSERT_EQUALS(static_cast<size_t>(2), c_out.size());
+	ASSERT_EQUALS(std::string("All"),    c_out[0].name);
+	ASSERT_EQUALS(std::string("Movies"), c_out[1].name);
+}
+
+
+TEST(State, WriteServersRoundtripAndOrder)
+{
+	CState s;
+	s.MutateServers([](std::map<std::uint32_t, ServerSnapshot> &cache) {
+		ServerSnapshot a;
+		a.ecid = 200;
+		a.name = "second-by-ecid";
+		cache.emplace(a.ecid, a);
+
+		ServerSnapshot b;
+		b.ecid = 100;
+		b.name = "first-by-ecid";
+		cache.emplace(b.ecid, b);
+	});
+
+	// std::map iterates ECID-ascending — the Servers() vector view
+	// inherits that ordering so the wire response is stable across
+	// refresher ticks.
+	const auto out = s.Servers();
+	ASSERT_EQUALS(static_cast<size_t>(2), out.size());
+	ASSERT_EQUALS(std::string("first-by-ecid"),  out[0].name);
+	ASSERT_EQUALS(std::string("second-by-ecid"), out[1].name);
+}
+
+
+TEST(State, AppendAmuleLogUncappedHistory)
+{
+	// Per-operator preference: amule log history is uncapped. Pushing
+	// thousands of lines must NOT trigger any trimming — operators
+	// rely on the full record being available for triage. A future
+	// `DELETE /logs/amule` mutation is the only intentional truncation
+	// path; until that lands, history grows monotonically.
+	CState s;
+	{
+		std::vector<std::string> first_batch;
+		for (int i = 0; i < 1000; ++i) {
+			first_batch.push_back("first-" + std::to_string(i));
+		}
+		s.AppendAmuleLog(std::move(first_batch));
+	}
+	ASSERT_EQUALS(static_cast<size_t>(1000), s.AmuleLog().size());
+
+	{
+		std::vector<std::string> second_batch;
+		for (int i = 0; i < 1000; ++i) {
+			second_batch.push_back("second-" + std::to_string(i));
+		}
+		s.AppendAmuleLog(std::move(second_batch));
+	}
+	const auto out = s.AmuleLog();
+	ASSERT_EQUALS(static_cast<size_t>(2000), out.size());
+	// Oldest-first preserved.
+	ASSERT_EQUALS(std::string("first-0"),     out[0]);
+	ASSERT_EQUALS(std::string("first-999"),   out[999]);
+	ASSERT_EQUALS(std::string("second-0"),    out[1000]);
+	ASSERT_EQUALS(std::string("second-999"),  out[1999]);
+}
+
+
+TEST(State, WriteServerInfoRoundtrip)
+{
+	CState s;
+	ServerInfoLog in;
+	in.text = "server hello\nline 2\nline 3\n";
+	s.WriteServerInfo(in);
+
+	const auto out = s.ServerInfo();
+	ASSERT_EQUALS(in.text, out.text);
+
+	// Overwrite semantics: a second write replaces (it doesn't
+	// append) — ServerInfoLog is amuled's full-snapshot text, not
+	// an incremental cursor.
+	ServerInfoLog replacement;
+	replacement.text = "totally different\n";
+	s.WriteServerInfo(replacement);
+	ASSERT_EQUALS(std::string("totally different\n"), s.ServerInfo().text);
+}
+
+
+TEST(State, WriteStatsTreeRoundtripRecursive)
+{
+	CState s;
+	StatsTreeNode root;
+	root.label = "root";
+	{
+		StatsTreeNode child;
+		child.label = "Transfer";
+		{
+			StatsTreeNode grand;
+			grand.label = "Total bytes transferred: 12.3 GiB";
+			child.children.push_back(grand);
+		}
+		root.children.push_back(child);
+	}
+	{
+		StatsTreeNode sib;
+		sib.label = "Connection";
+		root.children.push_back(sib);
+	}
+	s.WriteStatsTree(root);
+
+	const StatsTreeNode out = s.StatsTree();
+	ASSERT_EQUALS(std::string("root"),                                    out.label);
+	ASSERT_EQUALS(static_cast<size_t>(2),                                 out.children.size());
+	ASSERT_EQUALS(std::string("Transfer"),                                out.children[0].label);
+	ASSERT_EQUALS(static_cast<size_t>(1),                                 out.children[0].children.size());
+	ASSERT_EQUALS(std::string("Total bytes transferred: 12.3 GiB"),       out.children[0].children[0].label);
+	ASSERT_EQUALS(std::string("Connection"),                              out.children[1].label);
+}
+
+
+TEST(State, WriteGraphsRoundtripAllSeries)
+{
+	CState s;
+	StatsGraphs g;
+	g.interval_seconds = 1;
+	g.download_bps     = {100, 200, 300};
+	g.upload_bps       = {10, 20, 30};
+	g.connections      = {1, 2, 3};
+	g.kad_nodes        = {500, 600, 700};
+	g.session_download_bytes = 1024;
+	g.session_upload_bytes   = 256;
+	g.session_kad_bytes      = 4096;
+	s.WriteGraphs(g);
+
+	const StatsGraphs out = s.Graphs();
+	ASSERT_EQUALS(static_cast<std::uint32_t>(1),    out.interval_seconds);
+	ASSERT_EQUALS(static_cast<size_t>(3),           out.download_bps.size());
+	ASSERT_EQUALS(static_cast<std::uint32_t>(300),  out.download_bps[2]);
+	ASSERT_EQUALS(static_cast<std::uint32_t>(700),  out.kad_nodes[2]);
+	ASSERT_EQUALS(static_cast<std::uint64_t>(1024), out.session_download_bytes);
+	ASSERT_EQUALS(static_cast<std::uint64_t>(4096), out.session_kad_bytes);
+}
+
+
+TEST(State, SearchResultsRoundtripAndOrderByEcid)
+{
+	CState s;
+	s.MutateSearch([](std::map<std::uint32_t, SearchResult> &cache) {
+		SearchResult a;
+		a.ecid = 50;
+		a.hash = "aaaa0000aaaa0000aaaa0000aaaa0000";
+		a.name = "ascii-name.iso";
+		a.size = 10000;
+		a.source_count = 12;
+		cache.emplace(a.ecid, a);
+
+		SearchResult b;
+		b.ecid = 25;
+		b.hash = "bbbb1111bbbb1111bbbb1111bbbb1111";
+		b.name = "first-by-ecid.iso";
+		b.size = 7000;
+		b.complete_source_count = 5;
+		b.already_have = true;
+		cache.emplace(b.ecid, b);
+	});
+
+	// std::map iterates ECID-ascending → Search() vector is sorted.
+	const auto out = s.Search();
+	ASSERT_EQUALS(static_cast<size_t>(2),                 out.size());
+	ASSERT_EQUALS(std::string("first-by-ecid.iso"),       out[0].name);
+	ASSERT_EQUALS(std::string("ascii-name.iso"),          out[1].name);
+	ASSERT_TRUE(out[0].already_have);
+	ASSERT_FALSE(out[1].already_have);
+}
+
+
+TEST(State, ResetListsLeavesLogsAlone)
+{
+	// Logs survive an EC reconnect on purpose — the operator can see
+	// "EC disconnected at HH:MM" alongside earlier traffic. ResetLists
+	// must not nuke either log buffer.
+	CState s;
+	s.AppendAmuleLog({"persistent line"});
+	s.WriteServerInfo({"persistent server info"});
+	s.ResetLists();
+	ASSERT_EQUALS(static_cast<size_t>(1), s.AmuleLog().size());
+	ASSERT_EQUALS(std::string("persistent server info"),
+		s.ServerInfo().text);
+}
+
+
+TEST(State, ResetListsClearsAll)
+{
+	CState s;
+	s.MutateDownloads([](FileMap &cache) {
+		FileSnapshot d; d.ecid = 1; d.name = "a"; d.is_downloading = true;
+		cache.emplace(1, d);
+	});
+	s.MutateClients([](std::map<std::uint32_t, ClientSnapshot> &cache) {
+		ClientSnapshot c; c.ecid = 1; c.client_name = "b";
+		cache.emplace(1, c);
+	});
+	s.MutateShared([](FileMap &cache) {
+		// Same ECID; sets is_shared on the existing entry rather than
+		// creating a new map slot, matching the unified-map model.
+		auto it = cache.find(1);
+		if (it == cache.end()) {
+			FileSnapshot x; x.ecid = 1; x.name = "c"; x.is_shared = true;
+			cache.emplace(1, x);
+		} else {
+			it->second.is_shared = true;
+		}
+	});
+	ASSERT_EQUALS(static_cast<size_t>(1), s.Downloads().size());
+	ASSERT_EQUALS(static_cast<size_t>(1), s.Clients().size());
+	ASSERT_EQUALS(static_cast<size_t>(1), s.Shared().size());
+
+	s.ResetLists();
+	ASSERT_EQUALS(static_cast<size_t>(0), s.Downloads().size());
+	ASSERT_EQUALS(static_cast<size_t>(0), s.Clients().size());
+	ASSERT_EQUALS(static_cast<size_t>(0), s.Shared().size());
+}
+
+
+TEST(State, ConcurrentReadersDontTearSnapshot)
+{
+	// Spin up 4 readers + 1 writer for 100ms. The writer churns
+	// distinct snapshot values; readers verify they always observe
+	// a *self-consistent* snapshot (the four numeric fields below
+	// are written under one unique_lock, so a shared_lock reader
+	// must see them all from the same generation). A teared read
+	// would manifest as a mismatched (download_bps, upload_bps)
+	// pair, which we then assert against.
+
+	CState s;
+	std::atomic<bool> stop{false};
+	std::atomic<int>  observed{0};
+	std::atomic<int>  torn{0};
+
+	std::thread writer([&]{
+		std::uint64_t gen = 1;
+		while (!stop.load()) {
+			StatusSnapshot v;
+			v.download_bps    = gen;
+			v.upload_bps      = gen * 2;
+			v.ul_queue_len    = static_cast<std::uint32_t>(gen & 0xffffffff);
+			v.total_src_count = static_cast<std::uint32_t>(gen & 0xffffffff);
+			s.WriteStatus(v);
+			++gen;
+		}
+	});
+
+	std::vector<std::thread> readers;
+	for (int i = 0; i < 4; ++i) {
+		readers.emplace_back([&]{
+			while (!stop.load()) {
+				StatusSnapshot r = s.Status();
+				observed.fetch_add(1);
+				// Invariants enforced by the writer's single
+				// unique_lock acquisition: upload_bps == 2 *
+				// download_bps; ul_queue_len == total_src_count.
+				if (r.upload_bps != 2 * r.download_bps) torn.fetch_add(1);
+				if (r.ul_queue_len != r.total_src_count) torn.fetch_add(1);
+			}
+		});
+	}
+
+	std::this_thread::sleep_for(std::chrono::milliseconds(100));
+	stop.store(true);
+	writer.join();
+	for (auto &t : readers) t.join();
+
+	// Sanity: the loop actually exercised the contention path. A bar
+	// of `> 0` passes with a single observation, which a debug build
+	// or an over-loaded CI runner could plausibly produce — leaving
+	// the tear-detection harness inactive while the test still
+	// reports green. Require a meaningful number of reads instead;
+	// even a slow runner does ~10K reads per shared_lock-protected
+	// field in 100ms (single uncontended read is sub-microsecond),
+	// and torn-read detection needs many reads to catch the
+	// boundary anyway.
+	ASSERT_TRUE(observed.load() > 1000);
+	// And no read saw a torn snapshot.
+	ASSERT_EQUALS(0, torn.load());
+}
diff --git a/unittests/tests/StaticFsTest.cpp b/unittests/tests/StaticFsTest.cpp
new file mode 100644
index 0000000000..77a355ee95
--- /dev/null
+++ b/unittests/tests/StaticFsTest.cpp
@@ -0,0 +1,291 @@
+//
+// This file is part of the aMule Project.
+//
+// Copyright (c) 2003-2026 aMule Team ( https://amule-org.github.io )
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+
+#include <muleunit/test.h>
+
+#include "StaticFs.h"
+
+#include <cstdio>
+#include <cstdlib>
+#include <cstring>
+#include <fstream>
+#include <string>
+#include <vector>
+#include <sys/stat.h>
+#include <sys/types.h>
+
+#ifdef _WIN32
+#  include <direct.h>
+#  include <io.h>
+#  include <process.h>
+#  include <windows.h>
+#else
+#  include <unistd.h>
+#endif
+
+
+using namespace muleunit;
+using namespace webapi;
+
+
+namespace {
+
+// Per-test scratch dir. POSIX uses mkdtemp(); Windows builds a unique
+// name under %TEMP%. The dir is created empty; callers populate it and
+// must call RemoveAll() at the end of the test. muleunit's
+// DECLARE_SIMPLE has no TearDown hook, so cleanup is per-test.
+std::string MakeScratchRoot(const char *tag)
+{
+#ifdef _WIN32
+	char tmp[MAX_PATH];
+	DWORD n = GetTempPathA(MAX_PATH, tmp);
+	std::string base(tmp, n);
+	std::string dir = base + "amule-staticfs-" + tag + "-"
+		+ std::to_string(static_cast<long>(_getpid()));
+	_mkdir(dir.c_str());
+	return dir;
+#else
+	std::string tpl = "/tmp/amule-staticfs-";
+	tpl += tag;
+	tpl += "-XXXXXX";
+	std::vector<char> buf(tpl.begin(), tpl.end());
+	buf.push_back('\0');
+	if (!mkdtemp(buf.data())) return std::string();
+	return std::string(buf.data());
+#endif
+}
+
+
+bool MkSubdir(const std::string &path)
+{
+#ifdef _WIN32
+	return _mkdir(path.c_str()) == 0;
+#else
+	return mkdir(path.c_str(), 0755) == 0;
+#endif
+}
+
+
+// Write a single byte file. The content isn't load-bearing for these
+// tests — they only verify the resolver's accept/reject decision and
+// the resolved path, not file body.
+bool WriteFile(const std::string &path, const std::string &body)
+{
+	std::ofstream f(path.c_str(), std::ios::binary);
+	if (!f.is_open()) return false;
+	f << body;
+	return f.good();
+}
+
+
+void RemoveAll(const std::string &path)
+{
+	// Recursive rm via system(); test-scratch only, never on real
+	// data. Quote the path to survive spaces / odd chars in $TMPDIR.
+#ifdef _WIN32
+	std::string cmd = "rmdir /S /Q \"" + path + "\" >NUL 2>&1";
+#else
+	std::string cmd = "rm -rf \"" + path + "\" 2>/dev/null";
+#endif
+	(void)std::system(cmd.c_str());
+}
+
+}  // namespace
+
+
+DECLARE_SIMPLE(StaticFs)
+
+
+// ----------------------------------------------------------------------
+// Plain accept paths — file exists inside root.
+// ----------------------------------------------------------------------
+
+TEST(StaticFs, FileAtRootResolvesAndReturnsTrue)
+{
+	const std::string root = MakeScratchRoot("file-at-root");
+	ASSERT_TRUE(!root.empty());
+	const std::string asset = root + "/index.html";
+	ASSERT_TRUE(WriteFile(asset, "x"));
+
+	std::string out;
+	ASSERT_TRUE(ResolveWithinRoot(root, "index.html", out));
+	// Trailing separator is stripped by the resolver — strict equality
+	// against the file path is the cleanest check.
+	ASSERT_TRUE(out.size() >= asset.size() - 1);
+
+	RemoveAll(root);
+}
+
+
+TEST(StaticFs, RootWithTrailingSlashResolves)
+{
+	// Regression: Windows _fullpath() preserves a trailing slash from
+	// its input, which previously broke the prefix-comparison
+	// containment check. AMULEAPI_STATIC_DIR is baked with a trailing
+	// slash (cmake convention for dirs) so the bug shipped to every
+	// installed amuleapi binary until normalised here.
+	const std::string root = MakeScratchRoot("trailing-slash");
+	ASSERT_TRUE(!root.empty());
+	ASSERT_TRUE(WriteFile(root + "/index.html", "x"));
+
+	std::string out;
+	ASSERT_TRUE(ResolveWithinRoot(root + "/", "index.html", out));
+
+	RemoveAll(root);
+}
+
+
+TEST(StaticFs, NestedFileResolvesAndReturnsTrue)
+{
+	const std::string root = MakeScratchRoot("nested");
+	ASSERT_TRUE(!root.empty());
+	ASSERT_TRUE(MkSubdir(root + "/assets"));
+	ASSERT_TRUE(WriteFile(root + "/assets/app.js", "y"));
+
+	std::string out;
+	ASSERT_TRUE(ResolveWithinRoot(root, "assets/app.js", out));
+
+	RemoveAll(root);
+}
+
+
+// ----------------------------------------------------------------------
+// Reject paths — opaque false return for any failure mode, so the
+// dispatcher can map every miss to the same 404.
+// ----------------------------------------------------------------------
+
+TEST(StaticFs, MissingFileReturnsFalse)
+{
+	const std::string root = MakeScratchRoot("missing");
+	ASSERT_TRUE(!root.empty());
+
+	std::string out;
+	ASSERT_TRUE(!ResolveWithinRoot(root, "not-there.html", out));
+
+	RemoveAll(root);
+}
+
+
+TEST(StaticFs, MissingRootReturnsFalse)
+{
+	std::string out;
+	ASSERT_TRUE(!ResolveWithinRoot(
+		"/this/path/should/not/exist/amuleapi-test",
+		"index.html", out));
+}
+
+
+TEST(StaticFs, ParentEscapeRejectedEvenIfTargetExists)
+{
+	// Set up two sibling dirs under a common parent: `root/` and
+	// `outside/`. `outside/secret.txt` exists. A request for
+	// `../outside/secret.txt` under `root` must be rejected even
+	// though the file is real and stat'able — the canonical resolution
+	// would land outside root.
+	const std::string parent = MakeScratchRoot("parent-escape");
+	ASSERT_TRUE(!parent.empty());
+	const std::string root    = parent + "/root";
+	const std::string outside = parent + "/outside";
+	ASSERT_TRUE(MkSubdir(root));
+	ASSERT_TRUE(MkSubdir(outside));
+	ASSERT_TRUE(WriteFile(outside + "/secret.txt", "pwn"));
+
+	std::string out;
+	ASSERT_TRUE(!ResolveWithinRoot(root, "../outside/secret.txt", out));
+
+	RemoveAll(parent);
+}
+
+
+// ----------------------------------------------------------------------
+// Symlink containment — the security-critical case the resolver
+// exists for. POSIX only: Windows symlinks require elevation and
+// _fullpath() is lexical-only, so symlink behaviour isn't part of the
+// Windows wire-contract.
+// ----------------------------------------------------------------------
+
+#ifndef _WIN32
+TEST(StaticFs, SymlinkEscapingRootIsRejected)
+{
+	const std::string parent = MakeScratchRoot("symlink-escape");
+	ASSERT_TRUE(!parent.empty());
+	const std::string root    = parent + "/root";
+	const std::string outside = parent + "/outside";
+	ASSERT_TRUE(MkSubdir(root));
+	ASSERT_TRUE(MkSubdir(outside));
+	ASSERT_TRUE(WriteFile(outside + "/secret.txt", "pwn"));
+	// Plant a symlink INSIDE root that points OUTSIDE root.
+	const std::string link = root + "/leak.txt";
+	ASSERT_TRUE(symlink((outside + "/secret.txt").c_str(),
+		link.c_str()) == 0);
+
+	std::string out;
+	ASSERT_TRUE(!ResolveWithinRoot(root, "leak.txt", out));
+
+	RemoveAll(parent);
+}
+
+
+TEST(StaticFs, SymlinkPointingInsideRootIsAccepted)
+{
+	// Sanity: not every symlink is an attack. A link from one file in
+	// root to another file in root resolves cleanly and must be served.
+	const std::string root = MakeScratchRoot("symlink-inside");
+	ASSERT_TRUE(!root.empty());
+	ASSERT_TRUE(WriteFile(root + "/real.txt", "ok"));
+	const std::string link = root + "/alias.txt";
+	ASSERT_TRUE(symlink((root + "/real.txt").c_str(),
+		link.c_str()) == 0);
+
+	std::string out;
+	ASSERT_TRUE(ResolveWithinRoot(root, "alias.txt", out));
+
+	RemoveAll(root);
+}
+#endif  // !_WIN32
+
+
+// ----------------------------------------------------------------------
+// IsDir — the tiny stat-wrapper used by the discovery chain. The
+// trailing-slash tolerance matters for the configure-time
+// AMULEAPI_STATIC_DIR macro, which is set with a trailing slash for
+// concatenation with sub-paths.
+// ----------------------------------------------------------------------
+
+TEST(StaticFs, IsDirTrueForExistingDirectory)
+{
+	const std::string root = MakeScratchRoot("isdir-yes");
+	ASSERT_TRUE(!root.empty());
+	ASSERT_TRUE(IsDir(root));
+	ASSERT_TRUE(IsDir(root + "/"));  // trailing slash tolerated
+
+	RemoveAll(root);
+}
+
+
+TEST(StaticFs, IsDirFalseForFile)
+{
+	const std::string root = MakeScratchRoot("isdir-file");
+	ASSERT_TRUE(!root.empty());
+	const std::string file = root + "/just-a-file.txt";
+	ASSERT_TRUE(WriteFile(file, "x"));
+
+	ASSERT_TRUE(!IsDir(file));
+
+	RemoveAll(root);
+}
+
+
+TEST(StaticFs, IsDirFalseForMissingPath)
+{
+	ASSERT_TRUE(!IsDir("/path/that/should/not/exist/under/test"));
+	ASSERT_TRUE(!IsDir(""));
+}