chore(openspec): add edge host self-enrollment proposal

2026-07-13 17:55:40 +08:00
parent c72c31de04
commit a2802c6320
6 changed files with 227 additions and 0 deletions
@@ -0,0 +1,46 @@
+## ADDED Requirements
+
+### Requirement: Cloud supports opt-in self-service Host enrollment without a pre-issued token
+The Cloud Control Plane SHALL support a configuration flag that, when enabled, allows the Host enrollment operation to succeed for a caller presenting no valid enrollment-token credential, generating a `host_id` and persisting a Host row with no enrollment-token binding. When the flag is disabled (the default), enrollment behavior SHALL be unchanged from the existing token-required path.
+
+#### Scenario: Self-service enrollment is enabled and no token is presented
+- **WHEN** self-service enrollment is enabled and an edge instance presents a new instance identifier and a high-entropy candidate Host credential with no enrollment-token bearer credential
+- **THEN** the control plane returns a generated `host_id` and durably stores the Host credential digest with no enrollment-token binding
+
+#### Scenario: Self-service enrollment is disabled
+- **WHEN** self-service enrollment is disabled and an edge instance presents no enrollment-token bearer credential
+- **THEN** the control plane rejects the request exactly as it does today, without creating a Host identity
+
+#### Scenario: A valid configured enrollment token is still presented while self-service is enabled
+- **WHEN** self-service enrollment is enabled and an edge instance presents a valid unused configured enrollment token
+- **THEN** the control plane enrolls the Host using the existing token-bound path, including its idempotency and conflict semantics
+
+#### Scenario: Self-service enrollment retried by the same instance
+- **WHEN** an edge instance that previously completed self-service enrollment repeats enrollment with the same instance identifier and Host credential digest
+- **THEN** the control plane returns the original `host_id` without creating a duplicate Host
+
+### Requirement: Host Agent falls back to self-service enrollment when no enrollment token is configured
+The Host Agent SHALL attempt Host enrollment without an enrollment-token bearer credential when no `HOST_AGENT_ENROLLMENT_TOKEN` is configured and no cached Host identity exists, rather than treating the missing token as a startup configuration error.
+
+#### Scenario: Fresh install with no enrollment token configured
+- **WHEN** the Host Agent starts with no static Host credentials, no enrollment token, and no cached identity state
+- **THEN** it generates a local instance identifier and candidate Host credential and submits an enrollment request with no enrollment-token bearer credential
+
+#### Scenario: Self-service enrollment is rejected by the cloud
+- **WHEN** the Host Agent submits a self-service enrollment request and the cloud rejects it because self-service enrollment is disabled there
+- **THEN** the Host Agent surfaces a clear enrollment failure at startup and does not start background polling
+
+#### Scenario: A configured enrollment token is still honored
+- **WHEN** the Host Agent starts with `HOST_AGENT_ENROLLMENT_TOKEN` configured
+- **THEN** it uses the existing token-bound enrollment path unchanged
+
+### Requirement: Host Agent control-plane URL defaults to the managed cloud platform address
+The Host Agent SHALL default `HOST_AGENT_CONTROL_PLANE_URL` to `https://amcp.home.jerryyan.top` when the environment variable is not explicitly set, while continuing to allow the environment variable to override it.
+
+#### Scenario: No control-plane URL is configured
+- **WHEN** the Host Agent starts with `HOST_AGENT_CONTROL_PLANE_URL` unset
+- **THEN** it connects to `https://amcp.home.jerryyan.top`
+
+#### Scenario: Control-plane URL is explicitly configured
+- **WHEN** the Host Agent starts with `HOST_AGENT_CONTROL_PLANE_URL` set to a different HTTP(S) URL
+- **THEN** it connects to the explicitly configured URL instead of the default
@@ -0,0 +1,31 @@
+## 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