q792602257andClaude Opus 4.6
989fdbf878
Tests / Test passed: 794
Sync delta specs into main specs before archiving: modified cloud-control-plane, device-pool, and host-agent-protocol; created new edge-host-enrollment capability spec. openspec validate --specs reports 18/18 passing. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
72 lines
4.7 KiB
Markdown
72 lines
4.7 KiB
Markdown
# edge-host-enrollment Specification
|
|
|
|
## Purpose
|
|
Define how an edge Host Agent bootstraps its identity, enrolls local devices
|
|
with cloud-assigned identifiers, and maintains durable credentials and device
|
|
mappings across restarts without requiring static configuration.
|
|
|
|
## Requirements
|
|
|
|
### Requirement: Host bootstrap uses a one-time enrollment credential
|
|
The Cloud Control Plane SHALL provide a Host enrollment operation that authenticates a configured bootstrap credential, generates the authoritative `host_id`, and binds it to an edge-generated long-lived Host credential without storing the plaintext Host credential.
|
|
|
|
#### Scenario: New edge instance enrolls
|
|
- **WHEN** an edge instance presents a valid unused enrollment token, a new instance identifier, and a high-entropy candidate Host credential
|
|
- **THEN** the control plane returns a generated `host_id` and durably stores only the credential digest and enrollment binding
|
|
|
|
#### Scenario: Enrollment token is invalid
|
|
- **WHEN** an edge instance presents an unknown enrollment token
|
|
- **THEN** the control plane rejects enrollment without creating a Host identity or consuming any configured token
|
|
|
|
#### Scenario: Enrollment token is reused by another instance
|
|
- **WHEN** a consumed enrollment token is presented with a different instance identifier
|
|
- **THEN** the control plane returns a conflict and preserves the original Host binding
|
|
|
|
### Requirement: Host enrollment is idempotent across response loss
|
|
The Host enrollment operation SHALL return the existing cloud Host identity when the same instance repeats enrollment with the same bootstrap-token binding and Host credential digest.
|
|
|
|
#### Scenario: Identical enrollment is retried
|
|
- **WHEN** an edge instance repeats a successful enrollment request after losing the response
|
|
- **THEN** the control plane returns the original `host_id` without creating another Host or rotating the submitted Host credential
|
|
|
|
#### Scenario: Instance retries with a different Host credential
|
|
- **WHEN** an enrolled instance repeats enrollment with a different candidate Host credential
|
|
- **THEN** the control plane rejects the request and leaves the original Host credential binding unchanged
|
|
|
|
### Requirement: Cloud assigns Host-scoped device identities
|
|
An authenticated Host SHALL enroll each local device through an opaque Host-scoped local reference, and the control plane SHALL generate and durably return the `device_id` used by scheduling, heartbeat, leases, and assignment execution.
|
|
|
|
#### Scenario: Host enrolls a local device
|
|
- **WHEN** an authenticated Host submits a previously unknown local device reference and valid driver metadata
|
|
- **THEN** the control plane creates a device enrollment owned by that Host and returns a generated `device_id`
|
|
|
|
#### Scenario: Device enrollment is repeated
|
|
- **WHEN** the same Host repeats enrollment for the same local device reference
|
|
- **THEN** the control plane returns the existing `device_id` and does not create a duplicate enrollment
|
|
|
|
#### Scenario: Same local reference appears on another Host
|
|
- **WHEN** a different Host enrolls an identical local device reference
|
|
- **THEN** the control plane creates a distinct Host-scoped device enrollment rather than silently transferring ownership
|
|
|
|
### Requirement: Edge identity and device mappings survive restart
|
|
The Host Agent SHALL persist its generated instance identifier, long-lived Host credential, assigned Host ID, and local-to-cloud device mappings outside process memory and SHALL reuse them on later starts.
|
|
|
|
#### Scenario: Host Agent restarts after enrollment
|
|
- **WHEN** a managed Host Agent restarts with intact identity state
|
|
- **THEN** it authenticates with the previously assigned `host_id` and credential without consuming another enrollment token
|
|
|
|
#### Scenario: Device mapping is missing but Host identity remains
|
|
- **WHEN** a managed Host Agent has its Host identity but lacks a cached mapping for a configured local device
|
|
- **THEN** it repeats idempotent device enrollment and restores the original cloud `device_id`
|
|
|
|
#### Scenario: Enrollment response is lost before Host ID persistence
|
|
- **WHEN** the Host Agent persisted its candidate credential but did not persist the successful response
|
|
- **THEN** its next start retries the identical enrollment request and recovers the original `host_id`
|
|
|
|
### Requirement: Enrolled Host credentials are revocable
|
|
The cloud repository SHALL support revoking a dynamically enrolled Host credential, and authentication SHALL reject revoked credentials without deleting task or attempt history.
|
|
|
|
#### Scenario: Revoked Host sends heartbeat
|
|
- **WHEN** a Host presents a credential whose enrollment has been revoked
|
|
- **THEN** the internal API rejects the request and preserves existing cloud history for that Host and its devices
|