Add authenticated WebSocket serial terminal - dirty commit with front-

and backend issues

src/web_serial_transport.h

@@ -0,0 +1,128 @@
+/* SPDX-License-Identifier: GPL-3.0-only */
+/* Authenticated, bounded WebSocket transport for the serial session broker. */
+
+#pragma once
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+
+#include "esp_err.h"
+#include "esp_http_server.h"
+#include "session_broker.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define WEB_SERIAL_TRANSPORT_MAX_SESSIONS 2U
+#define WEB_SERIAL_TRANSPORT_MAX_TICKETS 4U
+#define WEB_SERIAL_TRANSPORT_TICKET_LENGTH 32U
+#define WEB_SERIAL_TRANSPORT_TICKET_CAPACITY \
+    (WEB_SERIAL_TRANSPORT_TICKET_LENGTH + 1U)
+#define WEB_SERIAL_TRANSPORT_TICKET_LIFETIME_SECONDS 30U
+#define WEB_SERIAL_TRANSPORT_MAX_RX_PAYLOAD 1024U
+#define WEB_SERIAL_TRANSPORT_TX_PAYLOAD_SIZE 512U
+
+#define WEB_SERIAL_TRANSPORT_TICKET_URI "/api/ws-ticket"
+#define WEB_SERIAL_TRANSPORT_WS_URI "/ws/serial"
+#define WEB_SERIAL_TRANSPORT_TICKET_QUERY_KEY "ticket"
+
+typedef struct {
+    uint64_t tickets_issued;
+    uint64_t tickets_consumed;
+    uint64_t tickets_rejected;
+    uint64_t tickets_expired;
+
+    uint64_t connections;
+    uint64_t connection_failures;
+    uint64_t disconnections;
+    uint64_t service_start_failures;
+    uint64_t broker_failures;
+
+    uint64_t writer_requests;
+    uint64_t writer_grants;
+    uint64_t writer_denials;
+    uint64_t writer_releases;
+    uint64_t writer_revocations;
+
+    uint64_t rx_ws_frames_accepted;
+    uint64_t rx_ws_frames_rejected;
+    uint64_t rx_ws_bytes_accepted;
+    uint64_t rx_ws_bytes_rejected;
+
+    uint64_t tx_binary_frames;
+    uint64_t tx_binary_bytes;
+    uint64_t tx_control_frames;
+    uint64_t tx_control_bytes;
+    uint64_t send_failures;
+    uint64_t queue_failures;
+    uint64_t protocol_errors;
+    uint64_t close_requests;
+} web_serial_transport_counters_t;
+
+typedef struct {
+    bool active;
+    bool writer;
+    bool tx_pending;
+    bool close_requested;
+    int socket_fd;
+    uint32_t generation;
+    session_broker_client_id_t broker_client_id;
+} web_serial_transport_session_snapshot_t;
+
+typedef struct {
+    bool initialized;
+    bool server_attached;
+    uint32_t active_sessions;
+    uint32_t active_tickets;
+    web_serial_transport_session_snapshot_t
+        sessions[WEB_SERIAL_TRANSPORT_MAX_SESSIONS];
+    web_serial_transport_counters_t counters;
+} web_serial_transport_snapshot_t;
+
+/*
+ * Allocate no per-session heap objects and start the permanent transport task.
+ * CONFIG_HTTPD_WS_SUPPORT must be enabled. CONFIG_HTTPD_QUEUE_WORK_BLOCKING must
+ * be disabled because that IDF mode can wait forever inside httpd_queue_work().
+ */
+esp_err_t web_serial_transport_init(void);
+
+/* Attach after httpd start; detach as part of stopping that same server. */
+esp_err_t web_serial_transport_attach_server(httpd_handle_t server);
+esp_err_t web_serial_transport_detach_server(httpd_handle_t server);
+
+/*
+ * Mint a one-time bearer ticket for an already-authenticated caller. The output
+ * is exactly 32 Base64URL characters plus a terminator and expires after 30
+ * monotonic seconds. Never log or persist the returned value.
+ */
+esp_err_t web_serial_transport_mint_ticket(char *ticket, size_t capacity);
+
+/*
+ * Convenience POST response helper for /api/ws-ticket. Authentication is
+ * intentionally outside this module: call this only after Basic authentication
+ * has already succeeded. Register it as HTTP_POST, not as a public handler.
+ */
+esp_err_t web_serial_transport_handle_authenticated_ticket_request(
+    httpd_req_t *request);
+
+/*
+ * Handler for /ws/serial. Register as HTTP_GET with is_websocket=true and
+ * handle_ws_control_frames=false. The initial upgraded GET authenticates the
+ * ticket; later invocations process one complete data frame.
+ */
+esp_err_t web_serial_transport_ws_handler(httpd_req_t *request);
+
+esp_err_t web_serial_transport_get_snapshot(
+    web_serial_transport_snapshot_t *snapshot);
+
+/* Clearing counters does not alter tickets, sessions, ownership, or queued data. */
+esp_err_t web_serial_transport_clear_counters(void);
+
+/* Invalidate outstanding tickets and close authenticated web serial sessions. */
+esp_err_t web_serial_transport_revoke_sessions(void);
+
+#ifdef __cplusplus
+}
+#endif