ESP32_Serial_Swiss_Army_Knife/docs/user_administration.md

User administration

Provision accounts locally first, then use the browser or authenticated admin SSH for routine administration.

Related guides: Web administration, firmware updates, command reference, security operations, and the web development contract.

Choose roles and keep local recovery

Account role	HTTPS	SSH
user	Serial terminal and status	UART1 serial stream through the broker
admin	Serial, Admin, and Settings	Device administration shell, not UART1

Use a separate user account for ordinary SSH serial work. Account roles do not override the broker's one-writer/multiple-observer rule. Admin SSH is not a serial broker client.

Keep physical UART0 administration available on a trusted computer. Native USB CDC is a different, network-independent UART1 data path, not an account-recovery console. Physical local access is not protected by network account authentication.

Create the first administrator

A new device with missing user-database storage starts with a persisted empty database. There is no default shared login, credential import, or user bootstrap command. Existing valid user databases retain their accounts unchanged; an older role-user account is not silently promoted.

On UART0:

user status
user list
user add maint admin
user show maint

Enter and confirm a unique password at the no-echo prompts. Passwords must contain 12–64 printable ASCII characters. Ctrl-C cancels a prompt. Usernames must match [a-z][a-z0-9_-]{0,15}: 1–16 characters, starting with a lowercase letter, followed by lowercase letters, digits, underscore, or hyphen.

To generate a password instead:

user add maint admin --generate

Use one creation form, not both for the same name. Generated passwords are displayed once: save the value in a password manager, avoid terminal recording, and do not share the output. Successful account changes persist immediately; no separate Save command is needed.

Before testing network login, compare web certificate info and ssh host-key info from trusted UART0 with the browser/SSH client's fingerprints. Follow security operations, then sign in through HTTPS. For SSH, connect using an interactive shell with the chosen account; exec/subsystem and file-transfer workflows are not supported.

Add and maintain accounts

Examples for UART0 or an authenticated admin SSH shell:

user add operator user
user list
user show operator
user password operator

The database holds at most eight accounts. Account summaries expose roles and public-key fingerprints, not passwords, salts, or verifiers. Passwords cannot be recovered from status output; set a replacement when necessary.

For an intentional role change or removal:

user role operator admin --force
user role operator user --force
user delete operator --force

These are separate examples, not a sequence to run routinely. Check the target and intended access before using --force. The final administrator cannot be deleted or demoted. Password, role, key, and deletion changes invalidate the affected username's outstanding tickets and active web/SSH sessions; unrelated accounts are not intentionally revoked. Your own change may disconnect you before you see its result. Inspect state and test the intended login before repeating an uncertain operation.

user password <username> --generate displays a replacement once. Admin SSH rejects generation for its own account to avoid losing the value during revocation; use trusted UART0 or the supported browser workflow instead.

Browser account management

Sign in as admin, open Settings → Accounts, and select the intended account for password, role, deletion, or authorized-key operations. Changes commit on successful submission; they are not RAM-only drafts awaiting a global Save.

The generated-password workflow first displays a new value without changing the account. Store it securely and acknowledge that it is saved, then explicitly submit the create/password change. Generation alone does not set a password; the saved acknowledgement is not proof that the subsequent operation succeeded. Self changes may end your login immediately.

The browser Admin shell has narrower account permissions than Accounts settings: status/list/show and selected interactive changes to other accounts are supported, but self changes, generated passwords, key commands, and database recovery are denied there. Use typed Accounts controls or UART0 rather than trying to bypass these restrictions.

Authorize an SSH client key

1. On a trusted client, generate or choose an OpenSSH Ed25519 or ECDSA P-256 key. Keep the private key on that client; import only the single-line .pub public key.

2. On UART0 or authenticated admin SSH, run:

   user key add operator
   

3. Paste the public-key line at the prompt. Ctrl-C cancels. Alternatively use the Accounts key-import controls in the browser.

4. Run user show operator and compare the reported key type and SHA256: fingerprint with the client's public key. Test a new SSH login with the intended username before closing local recovery access.

Each account supports three keys. Supported types are ssh-ed25519 and ecdsa-sha2-nistp256; RSA and OpenSSH certificate keys are not supported. Duplicate keys within an account are rejected. The same key can be assigned to multiple accounts, but access then follows the username selected at login.

Delete by the stable index shown in user show, not by its position in a displayed list:

user key delete operator 0 --force

Use user key clear operator --force only when intentionally removing all that account's keys. Key changes persist immediately and revoke that account's sessions. Changing a password does not remove authorized keys; review both after compromise. Authorized client keys are separate from the device's SSH host identity.

Forgotten passwords and database failure

For a healthy database, use UART0 and normal commands such as user password maint to restore access. First inspect user status and user list; do not erase flash or reset identities to repair a forgotten account password.

Only if database initialization has failed and the database is unavailable, deliberate UART0 recovery is:

user recover --force
user status
user add maint admin

Recovery destroys the user database's contents and rebuilds it empty. It refuses a healthy database, including a healthy empty database, and is unavailable over SSH/browser. It does not erase unrelated Wi-Fi/serial configuration or HTTPS/SSH identities. Recreate required accounts and authorized keys afterward. Check each command result; storage failures are not evidence of successful recovery.

web reset --force and ssh reset --force recover their respective device identities, not user accounts. Neither is a whole-device factory reset.

Persistence and security limits

Keep a private reprovisioning record of usernames/roles, public keys, settings, and verified device fingerprints; store passwords separately. There is no supported configuration/credential/identity backup-export command. Application-only firmware updates preserve stored bytes, but compatibility with the new firmware still matters.

NVS credentials are not protected against physical extraction by this workflow. Password verifiers can be attacked offline, and logical replacement does not securely erase historical flash contents. Keep the device and local ports controlled, avoid Internet exposure, and follow the security checklist.