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

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