browser/openspec/changes/implement-artifact-download-and-browser-transfer/specs/artifact-download-and-browser-transfer/spec.md

ADDED Requirements

Requirement: Browser artifact downloads are platform-mediated

The platform SHALL provide browser-safe artifact metadata and content download APIs that authorize access and do not expose storage backend credentials, raw host paths, or direct run sockets.

Scenario: Authorized artifact download starts

• WHEN an authorized operator requests download metadata for an available artifact in an accessible server or job context
• THEN the platform MUST return a browser-safe artifact reference or platform download route with filename, content type, size, checksum, and expiry metadata

Scenario: Unauthorized artifact download is denied

• WHEN a user or plugin page requests an artifact outside its server, job, or plugin permission scope
• THEN the platform MUST return a stable safe error and MUST NOT return artifact bytes or download references

Requirement: Artifact content reads are bounded and integrity-aware

The platform SHALL validate artifact availability, requested range/chunk bounds, checksum metadata, and response size before returning artifact content to browser clients.

Scenario: Available artifact content is read

• WHEN a browser client requests a valid byte range or full download for an available artifact
• THEN the platform MUST return content with safe headers and integrity metadata

Scenario: Incomplete artifact cannot be downloaded

• WHEN a browser client requests an uploading, failed, missing, or incomplete artifact
• THEN the platform MUST reject the request and leave artifact state unchanged

Requirement: Frontend exposes artifact download workflow

The frontend SHALL provide centralized API client methods and UI controls for artifact download/open flows from server, job, or plugin contexts.

Scenario: Operator downloads artifact

• WHEN an operator clicks an artifact download/open action
• THEN the page MUST request platform download metadata/content, show progress or completion state, and avoid raw path/credential display

Scenario: Download fails safely

• WHEN an artifact download request fails validation, authorization, or availability checks
• THEN the UI MUST show a safe error state without exposing backend paths, run sockets, storage credentials, or raw secrets

Requirement: Plugin bridge uses artifact references safely

The plugin bridge SHALL expose artifact actions as safe metadata or download references rather than raw bytes, host paths, direct run endpoints, or storage backend credentials.

Scenario: Plugin page opens artifact reference

• WHEN a plugin page requests an allowed artifact action
• THEN the platform/host MUST return a scoped artifact reference that the browser host can download through platform APIs

Scenario: Plugin page lacks artifact permission

• WHEN a plugin page requests artifact access without required manifest/page permission
• THEN the platform MUST deny the request before returning metadata, bytes, or download references

Requirement: Artifact download is verified end to end

The change SHALL include backend tests, frontend tests/build, plugin SDK tests if artifact bridge helpers are added, browser walkthrough evidence, structure validation, and strict OpenSpec validation.

Scenario: Verification commands pass

• WHEN the change is complete
• THEN platform tests, platform_web tests/typecheck/build, relevant plugin tests, scripts/check-structure.sh, and openspec validate implement-artifact-download-and-browser-transfer --strict MUST pass