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

## Context

Two systems are affected:

- **Host Agent** (`apps/device-host-agent/host_agent/`): `cli.py::main()` currently just calls `create_application().run()`. `config.py::load_host_agent_config()` defaults `HOST_AGENT_CONTROL_PLANE_URL` to `http://127.0.0.1:8001` and raises `HostAgentConfigurationError` unless one of (static `HOST_AGENT_HOST_ID`+`HOST_AGENT_TOKEN`, `HOST_AGENT_ENROLLMENT_TOKEN`, or an existing identity file at `HOST_AGENT_IDENTITY_PATH`) is present. `enrollment.py::resolve_host_identity` raises if `HOST_AGENT_ENROLLMENT_TOKEN` is empty and no cached `host_id` exists. `identity.py::HostIdentityStore` already establishes the atomic-write + `chmod 0600` pattern this change reuses for the new local account file.
- **Cloud Control Plane** (`packages/cloud-platform/cloud/`, `apps/cloud-api/`): `internal_api/api.py::enroll_host()` authenticates every enrollment request via `enrollment_auth.authenticate(request)` (`ConfiguredEnrollmentTokenProvider`, built from `CLOUD_ENROLLMENT_TOKENS_JSON`), returning `401` if no configured token digest matches the bearer header. `sql_repository.py::enroll_host()` first checks for an existing `HostRow` by `agent_instance_id` (idempotent retry, independent of the token) before checking whether the presented `enrollment_token_digest` is already bound to another host. Both `credential_digest` and `enrollment_token_digest` columns on `HostRow` (`db_models.py`) are already nullable — no migration is needed to store a `NULL` `enrollment_token_digest`.

This is a single-operator home deployment (`https://amcp.home.jerryyan.top`). The user has explicitly accepted that self-service enrollment means any network caller reaching that URL can register itself as a Host with no approval step, and asked that this not require a distribution/whitelist mechanism.

## Goals / Non-Goals

**Goals:**
- A fresh Host Agent install can complete first-run local setup and enroll against the cloud with zero pre-shared enrollment token, using a fixed default control-plane URL.
- Existing static-credential and token-based enrollment deployments keep working unchanged (`edge-host-enrollment` behavior is additive, not replaced).
- The local account gate is a one-time, interactive setup step, not an ongoing authentication mechanism for the unattended daemon.

**Non-Goals:**
- No multi-user account system, no roles, no network-facing login surface for the Host Agent. This is unrelated to the separate (unimplemented) `cloud-console-user-authentication` proposal's cloud-operator user model — different system, different threat model, not to be unified here.
- No re-authentication on every daemon start/restart. Once the local account file exists, the daemon starts unattended (required for systemd/launchd-managed services).
- No approval workflow, admin review queue, or per-request throttling/rate-limiting for self-service enrollment. The chosen mitigation for this deployment is network-perimeter control (the operator's own reverse proxy/firewall in front of `amcp.home.jerryyan.top`), not application-level throttling — see Risks.
- No removal of `CLOUD_ENROLLMENT_TOKENS_JSON`, static Host credentials, or the revocation path from `edge-host-enrollment`.

## Decisions

### D1. Local account credential storage: stdlib PBKDF2-HMAC-SHA256, not a new dependency
Store `{username, salt, iterations, hash}` as JSON via a new `host_agent/local_account.py::LocalAccountStore`, mirroring `identity.py::HostIdentityStore`'s atomic temp-file-then-`os.replace` write and `chmod 0600`. Hash with `hashlib.pbkdf2_hmac("sha256", password, salt, iterations=600_000)` (OWASP 2023 minimum for PBKDF2-SHA256), random 16-byte salt via `secrets.token_bytes`, compare with `hmac.compare_digest`.

**Alternatives considered:** Argon2id (via `argon2-cffi`, as the still-unimplemented `cloud-console-user-authentication` proposal plans for cloud operator accounts) is the stronger choice for an internet-facing, multi-user login system under credential-stuffing risk. Here the credential only gates a one-time local CLI prompt on a machine the operator already has filesystem access to — it is not re-checked on an ongoing basis and is not reachable over the network. Adding a new native-extension dependency to `device-host-agent` for that threat model is disproportionate. PBKDF2 via stdlib `hashlib` needs no new dependency and is adequate here.

### D2. First run is a real subcommand, not an implicit prompt-or-hang
`cli.py::main()` gains an explicit `setup` subcommand (`device-host-agent setup`) that interactively prompts (`getpass.getpass`) for username/password and writes the local account file, plus keeps the default (no subcommand) behavior as "run the daemon." When the default command runs and no local account file exists: if `sys.stdin.isatty()`, prompt inline (covers a manual first run in a terminal); if not a TTY (already running under systemd/launchd with no controlling terminal) and no account exists, fail fast with an explicit error telling the operator to run `device-host-agent setup` once, instead of hanging on a `getpass` call that can never be answered.

**Alternatives considered:** Always prompting inline on the default command is simpler but breaks headless service startup (a `getpass` call with no TTY either raises immediately with a confusing error or, depending on platform, blocks forever). A dedicated `setup` subcommand gives operators a clear, scriptable-once step, matching the existing precedent for interactive bootstrap (`device-cloud-admin`'s planned `getpass` flow in `cloud-console-user-authentication`, D... — same shape, independent implementation per D1/Non-Goals).

### D3. Cloud-side self-service enrollment is an additive, opt-in auth path
Add `CLOUD_SELF_SERVICE_ENROLLMENT_ENABLED` (bool, default `false`) to `control_config.py::CloudControlConfig`, following the existing default-off pattern used by `AI_PLANNER_ENABLED`/`SEMANTIC_ENRICHMENT_ENABLED` elsewhere in this codebase. When enabled, `apps/cloud-api/cloud_api/app.py` composes the enrollment auth provider as a small ordered chain instead of the single `ConfiguredEnrollmentTokenProvider`:

1. Try `ConfiguredEnrollmentTokenProvider` (existing behavior — a caller presenting a valid configured token still gets a token-bound principal, preserving `edge-host-enrollment`'s conflict/idempotency semantics for that path unchanged).
2. If that fails and self-service is enabled, fall back to a new `SelfServiceEnrollmentAuthProvider` that unconditionally returns an `EnrollmentPrincipal(id="self-service", token_digest=None)`.
3. Otherwise `401`, exactly as today.

`enroll_host()`'s existing call `pool.store.enroll_host(..., enrollment_token_digest=enrollment_principal.token_digest, ...)` needs no change — passing `None` is already handled by the nullable column, and `sql_repository.py`'s idempotent-retry-by-`agent_instance_id` path already runs before the token-conflict check, so retries from the same edge instance (same `agent_instance_id`) return the same `host_id` exactly as the token-based path does. The token-conflict lookup (`WHERE enrollment_token_digest = <digest>`) simply never matches `NULL`, so self-service requests never collide with each other on that column — every self-service call with a new `agent_instance_id` creates a new Host (expected; see Risks).

**Alternatives considered:** Making `enroll_host()` accept unauthenticated requests unconditionally (removing the auth check entirely) was rejected — it would silently change behavior for every existing deployment, including ones that never opt in. A configured, default-off flag keeps this strictly additive.

### D4. Host Agent falls back to self-service automatically when no token is configured
`enrollment.py::resolve_host_identity` currently raises `HostAgentConfigurationError` when `state.host_id is None and not config.enrollment_token`. Change it to instead call `client.enroll_host(...)` with no bearer credential when `enrollment_token` is empty (the client already needs a code path for "no token" — see below), rather than raising. `config.py::load_host_agent_config` drops the corresponding startup validation branch (`if not host_id and not enrollment_token and not identity_path.is_file(): raise ...`), since a missing enrollment token is no longer a configuration error — it now means "attempt self-service enrollment."

If the target cloud has `CLOUD_SELF_SERVICE_ENROLLMENT_ENABLED=false` (the default), this call fails with `401` from the cloud, surfaced as a runtime enrollment error at Host Agent startup — a clear, actionable failure (not a silent hang), and no worse than today's explicit config-time rejection.

Host Agent also passes the local account's username as `display_name` in the enrollment call when `HOST_AGENT_DISPLAY_NAME` is not explicitly set, so cloud-side operators can see who set up a self-enrolled Host without building any cross-system user linkage.

### D5. `HOST_AGENT_CONTROL_PLANE_URL` default becomes `https://amcp.home.jerryyan.top`, override preserved
`load_host_agent_config()` changes only the default value passed to `values.get("HOST_AGENT_CONTROL_PLANE_URL", "https://amcp.home.jerryyan.top")`. The existing `urlparse` scheme/netloc validation, and the environment-variable override, are unchanged — this keeps local/dev/test runs (which set the env var to point at a local cloud-api instance) working exactly as before.

## Risks / Trade-offs

- **[Risk] Unlimited anonymous Host registration** — with self-service enabled, any caller reaching the control-plane URL can create arbitrarily many Host rows (no rate limit, no approval). → **Mitigation**: accepted for this single-operator deployment; primary control is keeping the flag off everywhere except `amcp.home.jerryyan.top`'s own cloud-api environment, and relying on network-perimeter controls (reverse proxy/firewall) rather than application-level throttling, which this change deliberately does not add (see Non-Goals) to avoid a false sense of security from an easily-bypassed in-process limiter.
- **[Risk] Local account file loss or corruption blocks daemon startup on a TTY-less host** — if `HOST_AGENT_LOCAL_ACCOUNT_PATH` is deleted or unreadable on a systemd-managed host, the daemon now fails fast instead of starting. → **Mitigation**: this is intentional (matches the explicit local-gate requirement); the error message names the exact `device-host-agent setup` remediation step.
- **[Risk] Self-service Hosts are indistinguishable from token-enrolled Hosts once created** — `enrollment_token_digest = NULL` is the only marker of a self-service Host. → **Mitigation**: acceptable per existing `edge-host-enrollment` scoping (no admin UI in scope there either); an operator can still find/revoke via `revoke_enrolled_host` using `host_id`, and `NULL` vs non-`NULL` `enrollment_token_digest` is queryable if this needs auditing later.
- **[Trade-off] PBKDF2 instead of Argon2id (D1)** — weaker under GPU/ASIC attack than Argon2id, acceptable only because this credential is never exposed to a network-facing verification endpoint in this change.

## Migration Plan

1. Ship the cloud-side change first (`CLOUD_SELF_SERVICE_ENROLLMENT_ENABLED` defaulting to `false`) — no behavior change for any existing deployment.
2. Explicitly set `CLOUD_SELF_SERVICE_ENROLLMENT_ENABLED=true` in the `amcp.home.jerryyan.top` cloud-api deployment configuration only.
3. Ship the Host Agent change (new default URL, local-account gate, self-service fallback). Existing installs with a populated `HOST_AGENT_IDENTITY_PATH` are unaffected — `resolve_host_identity` returns early when `config.host_id and config.token` or a cached `host_id` already exists, so already-enrolled Hosts never re-enroll.
4. New installs: operator runs `device-host-agent setup` once, then starts the service normally; it self-enrolls against the fixed URL.

**Rollback**: setting `CLOUD_SELF_SERVICE_ENROLLMENT_ENABLED=false` again immediately stops new self-service enrollments; Hosts already enrolled that way keep authenticating normally (auth is by credential digest, independent of how `enrollment_token_digest` was populated) and can be individually revoked via the existing `revoke_enrolled_host` path if needed. Reverting `HOST_AGENT_CONTROL_PLANE_URL`'s default requires a Host Agent redeploy but does not affect already-enrolled identity state.

## Open Questions

- None blocking; the `edge-host-enrollment` change is implemented but not yet archived into `openspec/specs/` — this change's delta spec is authored against its pending spec content and should be reconciled (or the two archived together) when `edge-host-enrollment` is archived.