browser/openspec/changes/implement-plugin-bridge-and-sdk/specs/plugin-bridge-and-sdk/spec.md

ADDED Requirements

Requirement: Plugin bridge exposes only platform-mediated actions

The system SHALL define a plugin page bridge with narrow action names for server context reads, job dispatch, log queries, artifact references, scoped file requests, and platform-mediated AI invocation.

Scenario: Plugin page requests allowed bridge action

• WHEN a plugin page requests a bridge action declared by the bridge contract and permitted by its manifest metadata
• THEN the platform authorizes the request without exposing run credentials, raw host paths, direct sockets, storage backend credentials, platform auth storage, or AI provider keys

Scenario: Plugin page requests unsupported bridge action

• WHEN a plugin page requests an action outside the bridge contract
• THEN the platform rejects the request with a validation error before dispatching any run, file, log, artifact, or AI work

Requirement: Bridge permissions are enforced from manifest metadata

The system SHALL evaluate each bridge action against the installed plugin's declared permissions, page permissions, and AI purposes before allowing the action.

Scenario: Missing permission denies bridge action

• WHEN a plugin page requests files.request without the required file permission in its manifest or page permissions
• THEN the platform returns a denied bridge authorization decision and does not create a file job

Scenario: Allowed AI purpose authorizes AI request

• WHEN a plugin page requests ai.invoke with an AI purpose declared by the plugin manifest and the plugin has ai.invoke permission
• THEN the platform returns an allowed bridge authorization decision without exposing provider base URLs or API keys

Scenario: Undeclared AI purpose denies AI request

• WHEN a plugin page requests ai.invoke with a purpose not declared by the plugin manifest
• THEN the platform rejects or denies the request before invoking any AI provider

Requirement: Plugin SDK provides typed bridge helpers

The plugin SDK SHALL provide TypeScript types and helpers for bridge context, bridge action names, bridge request envelopes, bridge responses, permission checks, and safe errors.

Scenario: SDK builds typed bridge request

• WHEN plugin author code builds a request for a supported bridge action through SDK helpers
• THEN the request envelope includes plugin ID, route key, action, request ID, and scoped payload fields that can be validated by the platform host

Scenario: SDK detects missing local permission

• WHEN plugin author code checks a bridge context for a missing permission
• THEN the SDK helper returns a negative result without performing transport or privileged work

Requirement: Browser host creates safe bridge context

The frontend host SHALL construct plugin bridge context from installed plugin metadata, current route, selected server instance, safe theme tokens, and effective permissions only.

Scenario: Host context omits secrets

• WHEN the browser host creates bridge context for a plugin page
• THEN the context excludes raw AI keys, platform auth storage, run credentials, direct sockets, raw host paths, and storage backend credentials

Scenario: Host filters page permissions

• WHEN a plugin page declares route-specific permissions
• THEN the host context contains only permissions allowed by both the plugin manifest and the current page declaration

Requirement: Bridge implementation respects root ownership boundaries

The system SHALL keep plugin SDK, frontend host utilities, and platform authorization logic in their owning roots without casual cross-root imports.

Scenario: Contracts are copied through explicit root files

• WHEN bridge action or permission contracts are needed in multiple roots
• THEN each root owns an explicit local contract file or generated/copy artifact instead of importing implementation code from another root

Scenario: Structure validation passes after bridge implementation

• WHEN the bridge and SDK implementation is complete
• THEN repository structure validation passes without placing implementation code outside plugins/, platform_web/, or platform/