Add Serialized SSH Administrative Console

docs/command_reference.md

@@ -1,6 +1,6 @@
 # Command reference
 
-Use these commands from the UART0 `serial-tool>` administration console. Run `help` for the available root commands and `<group> help` for a group summary. Configuration changes are RAM-only unless explicitly saved.
+UART0 and authenticated `admin` SSH sessions use the same registered command implementations through one serialized dispatcher. Admin SSH exposes the registry subject to a transport policy; commands requiring physical recovery authority, raw UART0 prompts, asynchronous callback output, or mutation of the SSH service carrying the command remain UART0-only. Run `help` for root commands and `<group> help` for a group summary. Configuration changes are RAM-only unless explicitly saved.
 
 ## System
 
@@ -24,12 +24,13 @@ Use these commands from the UART0 `serial-tool>` administration console. Run `he
 | `user role <username> <user|admin> --force` | Change a role; the final administrator cannot be demoted. |
 | `user password <username>` | Set and confirm a new password without echo. |
 | `user password <username> --generate` | Replace a password with a generated value displayed once. |
-| `user key add <username>` | Prompt for one bounded OpenSSH public-key line. |
+| `user key add <username>` | Prompt on physical UART0 for one bounded OpenSSH public-key line. |
+| `user key add <username> <type> <base64>` | Import a key non-interactively; intended for authenticated admin SSH and also accepted on UART0. |
 | `user key delete <username> <0..2> --force` | Delete one key by the index shown by `user show`. |
 | `user key clear <username> --force` | Delete all public keys for an account. |
 | `user recover --force` | When normal user-database initialization failed, explicitly replace its blob from the current legacy network credential. |
 
-Usernames must match `[a-z][a-z0-9_-]{0,15}`. Passwords contain 12–64 printable ASCII characters. The fixed database supports eight users and three SSH keys per user; initial key types are `ssh-ed25519` and `ecdsa-sha2-nistp256`. A key may belong to only one account. Password verifiers, salts, raw key blobs, and passwords are absent from ordinary status output. `Ctrl-C` cancels a password or key prompt, and generated passwords are shown once.
+Usernames must match `[a-z][a-z0-9_-]{0,15}`. Passwords contain 12–64 printable ASCII characters. The fixed database supports eight users and three SSH keys per user; initial key types are `ssh-ed25519` and `ecdsa-sha2-nistp256`. A key may be assigned to multiple accounts but cannot be duplicated within one account. Password verifiers, salts, raw key blobs, and passwords are absent from ordinary status output. `Ctrl-C` cancels a password or key prompt, and generated passwords are shown once.
 
 On the first Phase 8A boot, the old shared `admin` credential is imported as a role-`user` account, not silently granted administrator rights. Run `user bootstrap` from physical UART0 to establish the administrator. Phase 8B now authenticates HTTPS and SSH passwords through this database and enables stored SSH public keys. Before bootstrap, `web credentials rotate --force` and `web reset --force` synchronize the migrated verifier; after bootstrap, that legacy credential is recovery-only and does not authenticate or alter role-based users.
 
@@ -130,14 +131,18 @@ HTTPS listens on port 443 only. Authenticate with any current user-database user
 | `ssh` / `ssh help` | Show SSH command usage. |
 | `ssh status` | Show service state and resource information. |
 | `ssh start` / `ssh stop` | Start or stop the SSH server. |
-| `ssh sessions` | List active SSH sessions with account, user role, authentication method, and broker role. |
+| `ssh sessions` | List active SSH sessions with account, user role, authentication method, route, broker role where applicable, and admin-worker state. |
 | `ssh disconnect <session-id>` | Disconnect one SSH session. |
 | `ssh counters` / `ssh clear-counters` | Show or clear SSH counters. |
 | `ssh host-key info` | Display the OpenSSH host-key fingerprint. |
 | `ssh host-key rotate --force` | Replace the persistent SSH host key. |
 | `ssh reset --force` | Explicitly replace invalid or missing SSH material. |
 
-SSH listens on port 22 and accepts user-database passwords plus stored `ssh-ed25519` and `ecdsa-sha2-nistp256` public keys. wolfSSH verifies key possession after the database authorizes the username/key pair; unsigned key probes do not complete authentication. Both `user` and `admin` currently receive the same broker-backed interactive shell/PTY serial stream. The administrative SSH shell arrives in Phase 8C. SSH does not provide `exec`, SFTP, SCP, forwarding, or subsystems. Verify the host fingerprint from `ssh host-key info` before connecting.
+SSH listens on port 22 and accepts user-database passwords plus stored `ssh-ed25519` and `ecdsa-sha2-nistp256` public keys. wolfSSH verifies key possession after the database authorizes the username/key pair; unsigned key probes do not complete authentication. A `user` receives the broker-backed UART1 serial stream. An `admin` receives the administration shell instead, does not become a broker client, and cannot acquire a UART1 writer lease.
+
+UART0 and admin SSH submit to one bounded queue, and one dispatcher task is the sole caller of `esp_console_run()`. Consequently, allowed SSH commands execute the canonical UART0 handlers and produce the same status and mutation behavior rather than using a second command implementation. Remote output is routed into the authenticated session's bounded output ring; only the SSH transport task accesses wolfSSH.
+
+The transport policy keeps `reboot`, `ping`/`wifi ping`, user bootstrap/recovery and interactive password/key forms, Wi-Fi secret entry/display, web recovery credentials/certificate/reset operations, and SSH start/stop/disconnect/reset/host-key mutation on physical UART0. Use generated user/password forms and `user key add <username> <type> <base64>` remotely. A connected administrator cannot generate its own replacement password remotely, preventing the one-time password from being lost during self-revocation. SSH does not provide `exec`, SFTP, SCP, forwarding, or subsystems. Verify the host fingerprint from `ssh host-key info` before connecting.
 
 ## Hardware diagnostics
 

docs/roadmap.md

@@ -38,7 +38,7 @@ These constraints apply across all phases:
 | 5B | Offline xterm.js WebSocket serial terminal | **Complete** |
 | 6 | Authenticated SSH serial transport | **Complete** |
 | 7 | Local display and button interface | **Complete** |
-| 8 | Role-based users and administrative access | **In progress (8A–8B complete; 8C–8E planned)** |
+| 8 | Role-based users and administrative access | **In progress (8A–8B complete; 8C validation pending; 8D–8E planned)** |
 | 9 | Security and production hardening | **Planned** |
 | 10 | Authenticated, rollback-capable OTA | **Planned** |
 | 11 | BLE serial transport and provisioning evaluation | **Planned** |
@@ -179,7 +179,7 @@ The software-crypto build no longer reproduces the HTTPD watchdog stall. This va
 
 ## Current and planned phases
 
-The order below is the current plan. Phase 7, Phase 8A, and Phase 8B are complete; later work remains planned or under evaluation. Detailed requirements should be finalized at the start of each phase, and optional features must not weaken the completed serial and recovery paths.
+The order below is the current plan. Phase 7, Phase 8A, and Phase 8B are complete; Phase 8C is implemented and awaiting target-hardware validation; later work remains planned or under evaluation. Detailed requirements should be finalized at the start of each phase, and optional features must not weaken the completed serial and recovery paths.
 
 ### Phase 7 — Local display and buttons
 
@@ -263,10 +263,14 @@ Implementation sequence:
    - **Completed SSH-key validation:** Ed25519 and ECDSA P-256 public-key login work for both roles, including normal unsigned probe followed by signed proof-of-possession. A public key may be assigned to multiple accounts but cannot be duplicated within one account; the SSH username selects the account principal. Unsupported or incorrect credentials remain rejected without granting a broker client.
    - **Completed ticket and revocation validation:** WebSocket tickets are account-bound, one-time, and expire as intended. Password, role, key, delete, and username-recreation mutations promptly revoke only the affected user's tickets and active network sessions, release any affected writer lease, and leave unrelated users connected.
    - **Completed recovery and concurrency validation:** The database-unavailable path fails closed and retains UART0 recovery. Concurrent USB CDC, WebSocket, SSH, UART1, and UART0 operation preserves normal serial writer/observer behavior. `web credentials rotate --force` remains recovery-only after bootstrap. `web reset --force` restarts HTTPS with a replacement certificate without revoking unrelated SSH sessions; browsers correctly require a fresh TLS certificate acceptance before reconnecting.
-3. **Phase 8C — SSH administrative shell — Planned**
-   - Route authenticated `admin` SSH shell sessions to the same registered administrative command set as UART0, without creating a broker client. Normal users continue to receive the existing broker-backed serial stream.
-   - Serialize command parsing safely because ESP-IDF console internals are process-global. Use bounded per-session input/output queues and a separate command worker; only the SSH owner task may call wolfSSH APIs.
+3. **Phase 8C — SSH administrative shell — Implemented; validation pending**
+   - Authenticated `admin` SSH shell sessions route to a bounded administration worker and never create a broker client or acquire a serial writer lease. Normal `user` sessions retain the existing broker-backed serial stream.
+   - UART0 and admin SSH now submit complete lines to one fixed-length request queue. A single dispatcher task is the sole caller of ESP-IDF's non-reentrant `esp_console_run()` and therefore executes the same registered command handlers for both entry routes. The former separately implemented reduced SSH command dispatcher has been removed.
+   - The worker uses fixed per-session command/input and output buffers. Queue records contain copied secret-free principals and generation-tagged session tokens; late work is discarded after disconnect, slot reuse, role change, password/key mutation, or deletion. Task-local standard streams route canonical handler output into the applicable bounded SSH ring, and only the SSH owner task calls wolfSSH APIs.
+   - Transport policy, rather than duplicate command implementations, restricts operations requiring physical recovery authority, raw UART0 prompts, asynchronous callback output, or mutation of the active SSH service. Remote-safe generated account/password operations and non-interactive Ed25519/ECDSA key import use the canonical `user` handler. Bootstrap, database recovery, manual password/key prompts, recovery credentials, Wi-Fi secrets, reboot, ping, and SSH identity/service mutation remain physical-console-only.
+   - `ssh sessions` and `ssh counters` identify broker versus admin-console routes, worker command state, queued admin output, admission failures, and input backpressure. Admin sessions are checked for a current `admin` principal before command execution and during the active-session reconciliation.
    - Keep SFTP, SCP, `exec`, forwarding, subsystems, and unauthenticated shells disabled.
+   - Pending target-hardware validation: route separation from the broker, administrative command input/editing/output/backpressure, generated user/password/key management including the longest ECDSA P-256 import, physical-only command rejection, targeted self/other-user revocation during queued work, UART0/SSH administration serialization, and concurrent USB/WebSocket/user-SSH/admin-SSH operation.
 4. **Phase 8D — Web user administration — Planned**
    - Add an admin-only user-management interface and typed, bounded APIs for account CRUD, roles, password generation/change, SSH-key management, and revocation. Never expose a generic HTTP endpoint that executes arbitrary CLI text.
    - Hide administrative navigation and controls for normal users, and enforce every authorization decision server-side so hidden UI is not treated as a security boundary.

docs/user_administration_tests.md

@@ -120,3 +120,38 @@ Run `web status`, `ssh sessions`, `web counters`, `ssh counters`, and `broker cl
 ### 5. Concurrency regression
 
 With USB CDC, two role-based network users, one WebSocket terminal, one SSH terminal, and UART1 traffic active, alternate writer ownership and mutate one account. Confirm binary transparency, observer isolation, bounded authentication/handshake behavior, UART0 responsiveness, and no unexpected disconnect of the unaffected user. Record memory, broker, web, SSH, and serial counters before and after. Repeat after reboot to verify passwords, roles, keys, and authentication methods persist.
+
+## Phase 8C SSH administrative shell
+
+Use one disposable `admin` and one disposable `user`. Keep UART0 attached throughout. The SSH server still accepts only shell sessions: `exec`, subsystem/SFTP/SCP, forwarding, and unauthenticated connections must remain rejected.
+
+### 1. Route separation and normal shells
+
+1. Connect as the normal user and confirm the existing broker-backed UART1 serial stream, broker client, and writer/observer behavior are unchanged.
+2. Connect as the administrator and confirm the `admin@serial-tool>` prompt appears. Run `help`, `status`, `memory`, `serial status`, `wifi status`, `web status`, `broker status`, and `broker clients`. Compare representative output with UART0 and confirm both routes execute the same registered command implementations.
+3. From UART0 run `ssh sessions` and `broker clients`. The user session must show `route=broker`; the admin session must show `route=admin-console`, `broker=0`, `broker-role=n/a`, and no writer lease. The admin session must not start UART1 or alter broker client/writer counts merely by connecting.
+
+### 2. Bounded command processing
+
+Exercise printable input, backspace, Ctrl-C, CR/LF, an empty line, and a line longer than the documented limit. Confirm the command line is bounded, overflow is discarded through a clear diagnostic, and a new prompt remains usable. Run `help`, `user list`, and `broker clients` in a normal ANSI terminal and confirm every line starts in column zero: canonical LF output must be normalized to CRLF without doubling handlers that already emit CRLF. Run an unsupported command and confirm it is rejected without affecting UART0 or the serial broker. Run the full root `help` output to exercise output-ring draining. With the SSH client temporarily unable to read output, confirm the worker applies input backpressure rather than accepting an unbounded command/output backlog; inspect `ssh counters` for admin-console admission and input-backpressure values.
+
+### 3. Remote account administration
+
+Run `user list`, `user show <name>`, `user add <name> user --generate`, `user password <name> --generate`, `user role <name> admin --force`, and the key delete/clear operations from the administrative shell. Confirm generated passwords appear once only on that authenticated channel, affected account sessions are revoked, and unrelated sessions remain connected.
+
+Import both supported key types through the remote form:
+
+```text
+user key add <username> ssh-ed25519 <base64-blob>
+user key add <username> ecdsa-sha2-nistp256 <base64-blob>
+```
+
+Confirm the full ECDSA P-256 command is accepted, fingerprints appear in `user show`, a duplicate on the same account is rejected, and the same key can be imported for a second account. Verify subsequent private-key SSH login uses the selected SSH username.
+
+### 4. Physical-only boundary and revocation
+
+Confirm `user bootstrap`, `user recover --force`, manually entered password/key workflows, Wi-Fi secret entry/display, legacy recovery credentials, web certificate/reset operations, `reboot`, `ping`, and SSH service/identity mutation remain unavailable from SSH and continue to work only on UART0 where applicable. Their rejection must occur before any handler attempts to read raw UART0 input.
+
+While an administrative command is queued or running, use UART0 to change that admin's role/password/key or delete it. Confirm no second remote administrative command runs after the mutation, the SSH session is revoked promptly, and queued output is not delivered to a reused SSH slot. Repeat with a different account mutation and confirm the administrator remains connected.
+
+Finally, issue commands concurrently from UART0 and admin SSH, including `user list`, long `help` output, and one UART0 interactive password or key prompt while an SSH command waits. Confirm the single dispatcher serializes all `esp_console_run()` calls, UART0 retains its line editing/history/completion, prompt input is consumed only from UART0, outputs are not mixed between transports, and there is no stack overflow, corrupted argument parsing, database damage, or broker disruption.