browser/openspec/changes/implement-plugin-page-bridge-execution/specs/plugin-page-bridge-execution/spec.md

ADDED Requirements

Requirement: Plugin page host creates safe executable bridge sessions

The frontend SHALL create plugin page bridge sessions from installed plugin metadata, selected route, selected server instance, safe theme tokens, and effective permissions only.

Scenario: Host session omits secrets

• WHEN a plugin page bridge session is created
• THEN the session context MUST omit raw platform auth storage, raw AI keys, provider base URL secrets, run credentials, direct sockets, raw host paths, and storage backend credentials

Scenario: Host session filters permissions

• WHEN a plugin page declares route-specific permissions
• THEN the host MUST include only permissions allowed by both plugin manifest metadata and the page declaration

Requirement: Plugin page bridge requests execute through platform APIs

The frontend SHALL dispatch plugin page bridge action requests through centralized platform API client methods rather than direct plugin fetches to arbitrary backend paths.

Scenario: Allowed request is dispatched

• WHEN a plugin page sends a supported action with required permissions and bounded payload
• THEN the host MUST submit a typed bridge execution request to the platform and return a typed bridge response to the plugin page

Scenario: Unsupported request is rejected locally or by platform

• WHEN a plugin page sends an unsupported action or unsafe payload
• THEN the host or platform MUST return a safe error envelope and MUST NOT dispatch run, file, artifact, log, job, or AI work

Requirement: Platform authorizes and executes supported bridge actions

The platform SHALL authorize every bridge execution request against plugin metadata and execute only supported platform-mediated actions.

Scenario: Missing permission prevents execution

• WHEN a plugin page requests an action without the required manifest/page permission
• THEN the platform MUST deny the request before side effects occur

Scenario: Allowed job dispatch request creates platform job

• WHEN a plugin page requests an allowed job dispatch action with a valid server scope
• THEN the platform MUST create or return a platform-mediated job reference without exposing run sockets, credentials, or host paths

Scenario: Allowed file request uses scoped dispatch

• WHEN a plugin page requests an allowed file action
• THEN the platform MUST use scoped file/config dispatch semantics and MUST NOT accept raw absolute host paths

Requirement: Bridge execution responses are safe and typed

The system SHALL return bridge execution responses as typed success or error envelopes with redacted result references.

Scenario: Execution succeeds

• WHEN a supported bridge action completes or queues work
• THEN the response MUST include request ID, action, status, and scoped result references without raw secrets or direct storage/run internals

Scenario: Execution fails

• WHEN validation, authorization, downstream service, or cancellation fails
• THEN the response MUST include a safe error code/message and MUST NOT include raw credentials, host paths, sockets, or provider keys

Requirement: Plugin page bridge execution is verified end to end

The change SHALL include backend tests, frontend tests/build, plugin SDK/example tests, 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, plugin tests/typecheck, scripts/check-structure.sh, and openspec validate implement-plugin-page-bridge-execution --strict MUST pass