agentic-mobile-control/openspec/changes/edge-host-self-enrollment/specs/host-agent-local-bootstrap/spec.md

ADDED Requirements

Requirement: Host Agent requires a local account before unattended operation

The Host Agent SHALL refuse to start its background polling loop until a local account (username and hashed password) exists on disk, and SHALL provide an explicit interactive command to create that account.

Scenario: No local account exists and setup is run interactively

• WHEN an operator runs the Host Agent's setup command on a machine with no local account file
• THEN the process prompts for a username and password, persists a hashed credential, and does not echo the password back

Scenario: Local account already exists

• WHEN the Host Agent's default (run) command starts and a valid local account file is already present
• THEN the process starts background polling immediately without prompting for any credential

Scenario: No local account exists and the process has no interactive terminal

• WHEN the Host Agent's default (run) command starts with no local account file and no controlling terminal available
• THEN the process exits with an error identifying the setup command to run, without hanging or prompting

Requirement: Local account credentials are stored hashed and access-restricted

The Host Agent SHALL persist the local account password only as a salted hash, never in plaintext, and SHALL restrict the credential file's filesystem permissions to the owning user.

Scenario: Local account file is written

• WHEN the setup command creates a new local account
• THEN the persisted file contains the username, a random per-account salt, an iteration count, and a derived password hash, and contains no plaintext password

Scenario: Local account file permissions

• WHEN the Host Agent writes or rewrites the local account file
• THEN the file is only readable and writable by the owning user

Scenario: Local account file is corrupted or unreadable

• WHEN the Host Agent attempts to load a local account file that is not valid, readable JSON in the expected shape
• THEN the process reports a clear error and does not start background polling