Add Serialized SSH Administrative Console

src/admin_ssh_console.h

@@ -0,0 +1,65 @@
+/* SPDX-License-Identifier: GPL-3.0-only */
+/* Bounded, transport-neutral administrative command worker for SSH sessions. */
+
+#pragma once
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+
+#include "esp_err.h"
+#include "user_database.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* Fits the longest supported ECDSA P-256 OpenSSH key import command. */
+#define ADMIN_SSH_CONSOLE_COMMAND_LINE_CAPACITY 256U
+
+typedef struct {
+    uint8_t slot_index;
+    uint32_t session_id;
+    uint32_t slot_generation;
+} admin_ssh_console_token_t;
+
+typedef struct {
+    bool active;
+    bool command_pending;
+    bool input_pending;
+    bool output_pending;
+    size_t input_length;
+    size_t output_length;
+} admin_ssh_console_session_snapshot_t;
+
+/* Starts the single command worker. It is the sole esp_console_run() caller. */
+esp_err_t admin_ssh_console_init(void);
+/* Called after all ESP-IDF commands are registered; starts the UART0 frontend. */
+esp_err_t admin_ssh_console_start_uart_frontend(void);
+
+/* Valid only while a registered command callback runs on the dispatcher task. */
+bool admin_ssh_console_dispatch_is_remote(void);
+const user_principal_t *admin_ssh_console_dispatch_principal(void);
+
+/* The token and principal are copied; no SSH or socket objects cross this boundary. */
+esp_err_t admin_ssh_console_open(const admin_ssh_console_token_t *token,
+                                 const user_principal_t *principal);
+void admin_ssh_console_close(const admin_ssh_console_token_t *token);
+
+/* Called only by the SSH owner task. Returns false when input must be backpressured. */
+bool admin_ssh_console_accepts_input(const admin_ssh_console_token_t *token);
+bool admin_ssh_console_feed_input(const admin_ssh_console_token_t *token,
+                                  const uint8_t *data, size_t length,
+                                  size_t *consumed);
+
+/* Called only by the SSH owner task; copies already-produced output without blocking. */
+esp_err_t admin_ssh_console_read_output(const admin_ssh_console_token_t *token,
+                                        uint8_t *data, size_t capacity,
+                                        size_t *received);
+esp_err_t admin_ssh_console_get_session_snapshot(
+    const admin_ssh_console_token_t *token,
+    admin_ssh_console_session_snapshot_t *snapshot);
+
+#ifdef __cplusplus
+}
+#endif