agentic-mobile-control/openspec/changes/cloud-control-plane-integration/specs/platform-sdk/spec.md

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