chore(openspec): add cloud control plane proposal

2026-07-12 14:30:29 +08:00
parent c94b3efe87
commit 99ea1509ef
9 changed files with 511 additions and 0 deletions
@@ -0,0 +1,51 @@
+## MODIFIED Requirements
+
+### Requirement: Pluggable authentication hook with a safe default
+The system SHALL evaluate every platform SDK route through a configurable scope-aware `AuthProvider` hook, and the deployable Cloud Control Plane SHALL reject anonymous access unless an explicit insecure-development override is enabled outside production.
+
+#### Scenario: Production starts without configured credentials
+- **WHEN** the Cloud Control Plane is configured as production without a usable public authentication provider or credentials
+- **THEN** startup or readiness fails rather than exposing anonymous platform routes
+
+#### Scenario: Explicit local anonymous override
+- **WHEN** a non-production operator explicitly enables the insecure anonymous-development override
+- **THEN** platform routes may use an anonymous principal and the application records that insecure mode is active
+
+#### Scenario: Custom AuthProvider is honored
+- **WHEN** a caller configures a custom `AuthProvider` that rejects a request or omits its required scope
+- **THEN** the platform SDK route returns an authentication or authorization error without executing its handler operation
+
+## ADDED Requirements
+
+### Requirement: Public API operations enforce scopes
+The public platform API SHALL require operation-specific scopes, including task submission, task reading, pool reading, plugin reading, and plugin administration.
+
+#### Scenario: Submit token has task scope
+- **WHEN** a principal with `tasks:submit` calls the task-submission endpoint
+- **THEN** the request is authorized subject to normal task validation
+
+#### Scenario: Non-admin token attempts plugin registration
+- **WHEN** an authenticated principal without `plugins:admin` calls plugin registration
+- **THEN** the API rejects the request before resolving or loading the plugin target
+
+### Requirement: Distributed task status exposes attempt outcomes
+The task-status API SHALL expose the existing lifecycle status and SHALL include non-secret assignment, attempt, and terminal failure metadata needed to diagnose distributed execution.
+
+#### Scenario: Query an active remote task
+- **WHEN** an authorized caller queries an assigned or dispatched task
+- **THEN** the response includes its status, assigned host/device, current attempt number, and lease expiry without exposing the lease credential
+
+#### Scenario: Query a failed remote task
+- **WHEN** an authorized caller queries a task that exhausted retries or failed during Runtime execution
+- **THEN** the response includes the terminal failure reason and attempt count
+
+### Requirement: Python SDK supports authenticated requests
+The Python `CloudClient` SHALL accept bearer credentials or an injectable authentication mechanism and SHALL apply authentication consistently to every public API method.
+
+#### Scenario: Client configured with bearer token
+- **WHEN** a caller constructs `CloudClient` with a valid bearer token and invokes a permitted method
+- **THEN** the client sends the authorization credential and returns the corresponding API result
+
+#### Scenario: Client receives authorization failure
+- **WHEN** the configured credential is missing, invalid, or lacks the required scope
+- **THEN** the client raises a typed HTTP/API error that preserves the response status without exposing the credential