Commander1024/ESP32_Serial_Swiss_Army_Knife
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add role-based user database administration

Browse Source
This commit is contained in:
Commander1024
2026-08-30 00:56:18 +02:00
parent 0c7b763bec
commit cd235445c7
14 changed files with 2235 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/command_reference.md
+30 -5
View File
@@ -10,6 +10,31 @@ Use these commands from the UART0 `serial-tool>` administration console. Run `he
| `reboot` | Drain console output briefly and restart the ESP32. |
| `status` | Show quick MAX3243 signal state. |
## Role-based users (Phase 8A)
| Command | Description |
|---|---|
| `user status` / `user list` | Show database generation, capacity, administrator/bootstrap state, and all secret-free account summaries. |
| `user show <username>` | Show one account's role, ID, authentication generation, and SSH-key fingerprints. |
| `user bootstrap` | Set and confirm the `admin` password without echo, then promote the migrated account to `admin`. |
| `user bootstrap --generate` | Bootstrap `admin` with a generated 24-character password displayed once. |
| `user add <username> <user|admin>` | Create an account using a bounded no-echo password and confirmation prompt. |
| `user add <username> <user|admin> --generate` | Create an account with a generated password displayed once. |
| `user delete <username> --force` | Delete an account; the pre-bootstrap migrated `admin` and final administrator are protected. |
| `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 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.
On the first Phase 8A boot, the existing shared `admin` HTTPS/SSH credential is imported as a role-`user` account, not silently granted administrator rights. Run `user bootstrap` from physical UART0 to establish the administrator. Before bootstrap, `web credentials rotate --force` and `web reset --force` synchronize the migrated verifier; reboot reconciliation retries an interrupted synchronization. After bootstrap, the legacy HTTPS/SSH credential and user-database passwords are intentionally separate until Phase 8B performs the authentication cutover. SSH public-key login is likewise enabled in Phase 8B, not Phase 8A.
`user recover --force` is a destructive physical recovery operation and succeeds only while the database is unavailable. It replaces the user blob with one role-`user` account derived from the current legacy credential; run `user bootstrap` afterward. It does not erase unrelated NVS data.
## Local display
| Command | Description |
@@ -90,13 +115,13 @@ Opening `/dev/ttyACM*` with DTR asserted creates the `usb-cdc` broker client, st
| `web status` | Show HTTPS and WebSocket state. |
| `web start` / `web stop` | Start or stop HTTPS service. |
| `web counters` / `web clear-counters` | Show or clear web counters. |
| `web credentials show` | Display the physical-console-only shared admin credentials. |
| `web credentials rotate --force` | Replace credentials and disconnect web and SSH sessions. |
| `web credentials show` | Display the physical-console-only legacy Phase 8A network credential. |
| `web credentials rotate --force` | Replace the legacy credential, apply pre-bootstrap migration synchronization, and disconnect web and SSH sessions. |
| `web certificate info` | Display certificate identity and fingerprint. |
| `web certificate rotate --force` | Replace the HTTPS certificate and private key. |
| `web reset --force` | Explicitly replace missing, incompatible, or damaged web material. |
| `web reset --force` | Explicitly replace missing, incompatible, or damaged legacy credentials and web material. |
HTTPS listens on port 443 only. Authenticate to `https://<device-address>/` as `admin` with the credential shown on UART0. The device serves its vendored xterm.js terminal without Internet access. Browser sessions use binary WebSocket frames and follow the broker's one-writer rule.
HTTPS listens on port 443 only. During Phase 8A, authenticate to `https://<device-address>/` as `admin` with the legacy credential shown on UART0; role-aware user-database authentication begins in Phase 8B. The device serves its vendored xterm.js terminal without Internet access. Browser sessions use binary WebSocket frames and follow the broker's one-writer rule.
## SSH serial transport
@@ -112,7 +137,7 @@ HTTPS listens on port 443 only. Authenticate to `https://<device-address>/` as `
| `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 uses the same `admin` credentials as HTTPS, but a separate host key. It accepts password-authenticated interactive shell/PTY sessions only; it does not provide public-key authentication, `exec`, SFTP, SCP, forwarding, or subsystems. Verify the fingerprint from `ssh host-key info` before accepting an SSH host key.
During Phase 8A, SSH listens on port 22 and uses the same legacy `admin` credential as HTTPS, but a separate host key. It accepts password-authenticated interactive shell/PTY serial sessions only. Stored per-user public keys and roles become active in Phase 8B/8C; Phase 8A does not yet provide public-key login or the administrative SSH shell. SSH does not provide `exec`, SFTP, SCP, forwarding, or subsystems. Verify the fingerprint from `ssh host-key info` before accepting an SSH host key.
## Hardware diagnostics