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