Loading files
This file is pinned to the selected release. Download the original to open it in your design tool.
// SPDX-License-Identifier: GPL-3.0-or-later
// Copyright (C) 2025 Jibril Sharafi
#pragma once
#include <Arduino.h>
#include <AsyncTCP.h>
#include <ESPAsyncWebServer.h>
#include <vector>
#include <AdvancedLogger.h>
#include <ArduinoJson.h>
#include <AsyncJson.h>
#include <HTTPClient.h>
#include <Update.h>
#include "esp_ota_ops.h"
#include "esp_task_wdt.h"
#include "constants.h"
#include "crashmonitor.h"
#include "customlog.h"
#include "custommqtt.h"
#include "customtime.h"
#include "mqtt.h"
#include "influxdbclient.h"
#include "issueregistry.h"
#include "ade7953.h"
#include "globals.h"
#include "binaries.h"
#include "utils.h"
#include "led.h"
#include "web_auth_gate.h"
#include "auth_lockout.h"
// Rate limiting
#define WEBSERVER_MAX_REQUESTS 6000
#define WEBSERVER_WINDOW_SIZE_SECONDS 600
#define MINIMUM_FREE_HEAP_OTA (10 * 1024) // Minimum free heap required for OTA updates
#define SIZE_REPORT_UPDATE_OTA (128 * 1024) // Print progress every X bytes during OTA update
#define OTA_TIMEOUT (3 * 60 * 1000) // Maximum time allowed for OTA process
#define OTA_TIMEOUT_TASK_NAME "ota_timeout_task"
#define OTA_TIMEOUT_TASK_STACK_SIZE (6 * 1024) // Strangely, this seemed to be starved with 4 kB
#define OTA_TIMEOUT_TASK_PRIORITY 2
// Here used to lie the delay before restarting or doing some operations to ensure the response is sent
// but then I undestood that the delay was (also) blocking the AsyncTCP task itself, so it was useless ¯\_(ツ)_/¯
// Health check task
#define HEALTH_CHECK_TASK_NAME "health_check_task"
#define HEALTH_CHECK_TASK_STACK_SIZE (6 * 1024)
#define HEALTH_CHECK_TASK_PRIORITY 1
#define HEALTH_CHECK_INTERVAL_MS (30 * 1000)
#define HEALTH_CHECK_TIMEOUT_MS (15 * 1000) // Allow handlers that legitimately take a few seconds (large config dumps, NVS writes)
#define HEALTH_CHECK_MAX_FAILURES 5 // Maximum consecutive failures before restart. 5 * 30s = 2.5 min of sustained failure - tolerant of transient stalls but still catches a real wedge
// Authentication
#define PREFERENCES_KEY_PASSWORD "password"
#define WEBSERVER_DEFAULT_USERNAME "admin"
#define WEBSERVER_DEFAULT_PASSWORD "energyme"
#define WEBSERVER_REALM "EnergyMe-Home"
#define MAX_PASSWORD_LENGTH 64
// MAX_PASSWORD_LENGTH + 1 for the terminator. NOT PASSWORD_BUFFER_SIZE (also 64), which is
// one byte short: Preferences::getString() returns the length INCLUDING the NUL, and
// _getWebPasswordFromPreferences rejects `res >= bufferSize`, so a 63-character password read
// into a 64-byte buffer returns 64 and is reported as a failed read. With the lockdown failing
// closed on a failed read, that locked the device out of its own gate - the change-password
// endpoint uses the same reader, so the only way out returned 500.
#define WEB_PASSWORD_BUFFER_SIZE (MAX_PASSWORD_LENGTH + 1)
// Validated when a password is SET, never when one is used to authenticate, so a device
// already holding a shorter password keeps working. Raised from 4 to match what the UI
// has always promised - the firmware, not the browser, is the authority.
#define MIN_PASSWORD_LENGTH 8
// Disco is a novelty, so the API - not the render engine - decides it always ends on
// its own. Absent or 0 duration means the default; anything longer is clamped.
#define DISCO_DEFAULT_DURATION_MS 15000
#define DISCO_MAX_DURATION_MS 60000
// API Request Synchronization
#define API_MUTEX_TIMEOUT_MS (2 * 1000) // Time to wait for API mutex for non-GET operations before giving up. Long timeouts cause wdt crash (like in async tcp)
// Buffer sizes
#define HTTP_HEALTH_CHECK_RESPONSE_BUFFER_SIZE 256 // Only needed for health check HTTP response to own server
// Content length validations
#define HTTP_MAX_CONTENT_LENGTH_LOGS_LEVEL 64
#define HTTP_MAX_CONTENT_LENGTH_UDP_DESTINATIONS 256
#define HTTP_MAX_CONTENT_LENGTH_CUSTOM_MQTT 512
#define HTTP_MAX_CONTENT_LENGTH_INFLUXDB 1024
#define HTTP_MAX_CONTENT_LENGTH_LED_BRIGHTNESS 64
#define HTTP_MAX_CONTENT_LENGTH_LED_COLOR 128
#define HTTP_MAX_CONTENT_LENGTH_ADE7953_CONFIG 1024
#define HTTP_MAX_CONTENT_LENGTH_ADE7953_SAMPLE_TIME 64
#define HTTP_MAX_CONTENT_LENGTH_ADE7953_CHANNEL_DATA 512
#define HTTP_MAX_CONTENT_LENGTH_ADE7953_REGISTER 128
#define HTTP_MAX_CONTENT_LENGTH_ADE7953_ENERGY 256
#define HTTP_MAX_CONTENT_LENGTH_ADE7953_WAVEFORM_ARM 64
#define HTTP_MAX_CONTENT_LENGTH_MQTT_CLOUD_SERVICES 64
#define HTTP_MAX_CONTENT_LENGTH_PASSWORD 256
#define HTTP_MAX_CONTENT_LENGTH_NETWORK 256
#define HTTP_MAX_CONTENT_LENGTH_ISSUES_ACK 128
#define HTTP_MAX_CONTENT_LENGTH_NVS_ENTRY 8192 // Large enough for a cert/key PEM value
// Dev-only NVS browser/editor (see _serveNvsDebugEndpoints)
#define NVS_DEBUG_MAX_ENTRIES 512 // 64 KB nvs partition / ~32 B min entry size, generous upper bound
#define NVS_DEBUG_MAX_NAMESPACES 32
#define NVS_NAME_BUFFER_SIZE 16 // NVS namespace/key names are capped at 15 chars + null
#define NVS_DEBUG_STRING_VALUE_BUFFER_SIZE 512 // Non-sensitive string values only; credential-looking keys are redacted
class CustomMiddleware : public AsyncMiddleware {
public:
void run(AsyncWebServerRequest *request, ArMiddlewareNext next) override {
// Log incoming request details
LOG_VERBOSE("Request received: %s %s from %s",
request->methodToString(),
request->url().c_str(),
request->client()->remoteIP().toString().c_str());
// Increment request count before processing
statistics.webServerRequests++;
// Continue with the middleware chain
next();
// Check for error responses after processing
AsyncWebServerResponse* response = request->getResponse();
if (response && response->code() >= HTTP_CODE_BAD_REQUEST) {
statistics.webServerRequests--;
statistics.webServerRequestsError++;
LOG_DEBUG("Request from %s completed with error: %s %s -> HTTP %d",
request->client()->remoteIP().toString().c_str(),
request->methodToString(),
request->url().c_str(),
response->code());
} else if (response) {
LOG_VERBOSE("Request from %s completed successfully: %s %s -> HTTP %d",
request->client()->remoteIP().toString().c_str(),
request->methodToString(),
request->url().c_str(),
response->code());
}
}
};
// Applies the generic request ceiling to UNAUTHENTICATED requests only.
//
// A local-first meter's authenticated caller is its owner; throttling their dashboard, Home
// Assistant, Modbus poller and automation against a shared global budget is a misfeature, and
// the global limiter would let one busy legitimate client 429 another. So authenticated
// traffic (anything carrying an Authorization header) is never rate-limited here. What remains
// is the actual DoS surface - credential-less request floods that could wedge the AsyncTCP
// task - which is exactly what the ceiling should bound.
//
// This is not the brute-force defence: a wrong-password guess carries an Authorization header,
// so it skips this and is handled by the per-source lockout instead. This only sees the
// credential-less first legs of handshakes and unauthenticated probes/floods, which is why a
// generous global ceiling is harmless here.
class UnauthenticatedRateLimitMiddleware : public AsyncMiddleware {
public:
void setInner(AsyncRateLimitMiddleware *inner) { _inner = inner; }
void run(AsyncWebServerRequest *request, ArMiddlewareNext next) override {
if (request->hasHeader("Authorization") || _inner == nullptr) { next(); return; }
_inner->run(request, next);
}
private:
AsyncRateLimitMiddleware *_inner = nullptr;
};
// Throttles repeated failed logins per source address.
//
// Both halves of the job in one middleware: it refuses a locked-out source before the chain
// continues, and it reads the outcome afterwards to decide whether that was a failed login.
// Registered ahead of digestAuth, so a locked-out source never costs a digest MD5.
//
// The thresholds and durations are NOT here - they live in lib/auth_lockout and are unit
// tested on the host. This class supplies the clock and the address and acts on the answer.
class AuthLockoutMiddleware : public AsyncMiddleware {
public:
void run(AsyncWebServerRequest *request, ArMiddlewareNext next) override {
AsyncClient *client = request->client();
if (client == nullptr) { next(); return; }
uint32_t address = (uint32_t)client->remoteIP();
uint64_t nowMs = _clock ? _clock() : 0;
uint32_t retryAfterSeconds = 0;
if (AuthLockout::isLocked(_table, address, nowMs, retryAfterSeconds)) {
AsyncWebServerResponse *response = request->beginResponse(HTTP_CODE_TOO_MANY_REQUESTS, "application/json",
"{\"success\":false,\"error\":\"Too many failed login attempts. Try again later.\"}");
response->addHeader("Retry-After", String(retryAfterSeconds));
request->send(response);
return;
}
next();
AsyncWebServerResponse *response = request->getResponse();
if (response == nullptr) return; // no outcome observed - record nothing
if (response->code() == HTTP_CODE_UNAUTHORIZED) {
// THE decision this whole feature turns on. Every digest handshake opens with a
// credential-less request that is answered 401; a browser does this on every fresh
// session. Counting those would lock out the legitimate owner within a few page
// loads. Only a rejection of credentials that were actually supplied is a failed
// login - and an attacker must supply credentials to test a password, so nothing
// defensive is given up. Credential-less flooding is the rate limiter's job.
if (request->hasHeader("Authorization") && AuthLockout::recordFailure(_table, address, nowMs)) {
// Log and count once, on the failure that crosses the threshold - so a
// sustained attack is visible in the log and, via the counter, surfaces as a
// device issue the owner (and the cloud shadow) can see.
statistics.webServerAuthLockouts++;
LOG_WARNING("Locked out %s after repeated failed logins", request->client()->remoteIP().toString().c_str());
}
return;
}
// Clearing a source requires a real authentication success: the request both carried
// credentials AND got past digestAuth (a non-401 outcome, including the 403 from the
// default-password guard, which only fires on an authenticated caller). A request with
// no Authorization header is never that - it is a handshake opening leg, an open-route
// hit, or a 429 from the unauthenticated rate limiter - so it records nothing. Without
// this guard, a credential-less request that trips the global limiter comes back 429,
// is read as "success", and clears a source's accumulated failures, letting an attacker
// interleave floods to stay below the lockout threshold forever.
if (request->hasHeader("Authorization")) AuthLockout::recordSuccess(_table, address, nowMs);
}
// The clock is injected rather than called directly: this header is pulled in by
// translation units where utils.h has not been seen yet, and a monotonic millisecond
// clock is exactly the sort of thing worth being able to substitute anyway.
void begin(std::function<uint64_t()> clock) {
_clock = clock;
AuthLockout::init(_table);
}
// For handlers that run BEFORE the middleware chain. Upload and body callbacks fire during
// body parsing, so this middleware has not gated the request yet - which means an upload
// handler that does its own auth (as the OTA and restore routes must, since middleware auth
// arrives after the image is already written) would run a full password check on every
// attempt regardless of lock state, and a correct guess would reach Update.begin() before
// the masking 429. Those handlers call this first to apply the same throttle at the point
// where they authenticate. True when the source is locked; retryAfterSeconds is then set.
bool isSourceLocked(AsyncWebServerRequest *request, uint32_t &retryAfterSeconds) {
AsyncClient *client = request->client();
if (client == nullptr) { retryAfterSeconds = 0; return false; }
return AuthLockout::isLocked(_table, (uint32_t)client->remoteIP(), _clock ? _clock() : 0, retryAfterSeconds);
}
private:
// Touched only from the AsyncTCP task - every middleware and handler runs there - so it is
// not shared state and takes no mutex. Do not read it from another task without adding one.
AuthLockout::Table _table;
std::function<uint64_t()> _clock = nullptr;
};
// The DENY response, shared with the upload path's own early check in customserver.cpp.
// That second call site is not a copy of the *rule* (both go through the same
// WebAuthGate::evaluate()) - it exists because ESPAsyncWebServer runs upload/body
// handlers during body parsing, before the middleware chain gets a turn, so uploads
// cannot rely on this middleware ever running. Centralizing just the response text
// here means there is still only one string to edit.
inline void sendDefaultPasswordDeniedResponse(AsyncWebServerRequest *request) {
request->send(HTTP_CODE_FORBIDDEN, "application/json",
"{\"success\":false,\"error\":\"The default web password is still in use. Change it at / or via POST /api/v1/auth/change-password before using the API.\",\"reason\":\"default_password\"}");
}
// Refuses to serve a device that is still holding the shipped default web password.
//
// The rule itself is not here - it lives in lib/web_auth_gate and is unit-tested on the
// host. This class is the adapter: read the cached flag, ask, act. Do not restate the
// allowlist here, or in customserver.cpp. wifi_provisioning::isAuthBypassAllowed() is what
// happens when that discipline slips: a tested rule nobody calls, and an untested inline
// copy that has already drifted from it.
class DefaultPasswordGuardMiddleware : public AsyncMiddleware {
public:
// The flag lives in customserver.cpp; the middleware is handed a reader for it rather
// than reaching across, so the "no NVS, no lock, no allocation on the request path"
// property stays visible at the call site.
void setStateReader(std::function<bool()> usingDefaultPassword) { _usingDefaultPassword = usingDefaultPassword; }
// Tells the guard whether a request arrived on the device's own SoftAP, which widens
// the allowlist to the provisioning surface. Must stay as cheap as the provisioning
// filters it mirrors - a volatile load and an address compare, no lock, no NVS.
//
// Note this middleware is not free of allocation *overall*: AsyncMiddlewareChain::_runChain
// passes `next` by value, and that std::function exceeds SSO, so every middleware in the
// chain costs one heap alloc/free per request. Adding this one adds another. The members
// below are captureless and do not allocate when called; the chain does.
void setApOriginReader(std::function<bool(AsyncWebServerRequest *)> isApOrigin) { _isApOrigin = isApOrigin; }
void run(AsyncWebServerRequest *request, ArMiddlewareNext next) override {
// Fail closed: an unconfigured guard refuses rather than waves through. The AP
// reader fails closed the other way - unknown origin is treated as the LAN, which
// is the narrower allowlist.
bool locked = _usingDefaultPassword ? _usingDefaultPassword() : true;
bool fromAp = _isApOrigin ? _isApOrigin(request) : false;
switch (WebAuthGate::evaluate(locked, fromAp, request->url().c_str())) {
case WebAuthGate::Action::ALLOW:
next();
return;
case WebAuthGate::Action::REDIRECT_TO_ROOT: {
// "/" serves the password change page while locked down.
AsyncWebServerResponse *response = request->beginResponse(302, "text/plain", "Change the default password first");
response->addHeader("Location", "/");
request->send(response);
return;
}
case WebAuthGate::Action::DENY:
// Machine-readable, so the browser client can bounce a stale tab to the gate
// and a script can tell this apart from an ordinary authorization failure.
sendDefaultPasswordDeniedResponse(request);
return;
}
}
private:
// Never store `next` and call it later: AsyncMiddlewareChain::_runChain captures it and
// the list iterator by reference into a lambda that lives on its own stack frame.
std::function<bool()> _usingDefaultPassword = nullptr;
std::function<bool(AsyncWebServerRequest *)> _isApOrigin = nullptr;
};
namespace CustomServer {
// Web server management
void begin();
void stop();
// Authentication management
void updateAuthPasswordWithOneFromPreferences();
bool resetWebPassword(); // This has to be accessible from buttonHandler to physically reset the password
// Task information
TaskInfo getHealthCheckTaskInfo();
TaskInfo getOtaTimeoutTaskInfo();
}f4329a85eThis file is pinned to the selected release. Download the original to open it in your design tool.