first commit

2026-07-11 14:56:10 +08:00
commit 7e05d0a4e7
660 changed files with 78119 additions and 0 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-06
@@ -0,0 +1,60 @@
+## Context
+
+`implement-plugin-bridge-and-sdk` defines typed bridge envelopes and authorization decisions, but execution is still theoretical. This change makes plugin pages useful in the console by adding the host-side transport and backend execution adapter for allowed bridge actions. The platform remains authoritative: browser host checks improve UX, but backend validation decides whether a request can execute.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Create safe plugin bridge sessions in `platform_web` from registry/page/server context.
+- Dispatch plugin page bridge requests through centralized frontend API client methods.
+- Add backend execution behavior for supported bridge actions by calling existing platform services instead of proxying arbitrary API paths.
+- Return typed success/error envelopes to plugin pages.
+- Add tests and browser walkthrough evidence for allowed actions, denied actions, and no secret exposure.
+
+**Non-Goals:**
+
+- No arbitrary HTTP proxy from plugin pages to platform APIs.
+- No direct run sockets, host paths, raw credentials, auth storage, artifact storage credentials, or raw AI provider keys in plugin page context or responses.
+- No iframe sandbox policy overhaul beyond what is necessary for bridge host execution.
+- No package download, plugin marketplace commerce, billing, cloud host sales, or provider marketplace behavior.
+
+## Decisions
+
+### Decision 1: Backend execution uses an action switch over safe services
+
+Bridge execution maps each supported action to a named backend service method, such as server context reads, job dispatch, log queries, artifact open/download metadata, scoped file dispatch, or platform-mediated AI invocation. Unsupported actions fail before side effects.
+
+Alternative considered: accept a plugin-supplied URL/path and proxy it. Rejected because arbitrary proxying bypasses reviewable permission mapping.
+
+### Decision 2: Host context is short-lived and derived
+
+The frontend host builds session context from selected server instance, plugin page metadata, safe theme tokens, and effective permissions. It does not persist platform auth tokens or raw backend state in plugin page-visible structures.
+
+Alternative considered: pass the normal platform API client or auth storage into plugin pages. Rejected because plugin code is not a credential boundary.
+
+### Decision 3: Execution envelopes are typed and auditable
+
+Every bridge execution request carries request ID, plugin ID, route key, action, server instance scope, purpose metadata, and bounded payload. Backend responses include allowed/denied state, typed result, and safe error details.
+
+Alternative considered: reuse authorization-only DTOs for execution results. Rejected because execution needs result references and error details distinct from preflight authorization.
+
+## Risks / Trade-offs
+
+- [Risk] Supported bridge action behavior depends on other platform capabilities. Mitigation: actions whose downstream service is not available return explicit unsupported/deferred errors and tests cover the available set.
+- [Risk] Browser host checks can be bypassed. Mitigation: backend validation repeats all permission and safety checks.
+- [Risk] Plugin page UI can create noisy request loops. Mitigation: host utilities include request bounds and cancellation/error state tests.
+
+## Migration Plan
+
+1. Add bridge execution DTOs/domain/validators/services/routes in platform.
+2. Add frontend host transport/API client/session utilities and tests.
+3. Update plugin SDK/example tests to use execution envelopes.
+4. Update docs and run full verification including browser walkthrough.
+
+Rollback removes bridge execution routes, host transport utilities, SDK example changes, and this change's artifacts before downstream plugin pages depend on it.
+
+## Open Questions
+
+- Which sandbox mechanism should eventually host third-party plugin page assets in production?
+- Whether bridge execution audit events should be a separate observability change.
@@ -0,0 +1,27 @@
+## Why
+
+The plugin SDK and authorization contract exist, but plugin pages still cannot execute real platform-mediated bridge actions from the management console. Operators need plugin UI pages to request allowed server, job, log, artifact, file, and AI capabilities through a host bridge that keeps platform auth, run sockets, host paths, and provider credentials hidden.
+
+## What Changes
+
+- Add frontend plugin page host execution utilities for creating safe bridge sessions and dispatching bridge action requests through platform APIs.
+- Add platform bridge execution routes/services that authorize each request and fan out only to existing safe platform capabilities.
+- Add plugin SDK/example coverage for request envelopes and host-mediated response/error handling.
+- Update plugin page documentation and tests to prove unsupported actions, missing permissions, raw paths, sockets, credentials, and raw AI keys are rejected.
+- Add browser walkthrough for an embedded plugin page workflow.
+
+## Capabilities
+
+### New Capabilities
+
+- `plugin-page-bridge-execution`: Executes plugin page bridge requests through the platform host and backend authorization layer without exposing unsafe internals.
+
+### Modified Capabilities
+
+- Builds on `plugin-bridge-and-sdk`, `config-write-and-file-dispatch`, `platform-mediated-ai-invocation`, and artifact/log/job capabilities as they become available.
+
+## Impact
+
+- Affects `platform/`, `platform_web/`, and `plugins/`.
+- Adds backend DTO/service/API behavior for bridge execution, frontend bridge host transport, SDK/example tests, and documentation.
+- Does not add direct plugin-to-run access, direct platform auth sharing, raw credentials, host path exposure, billing, cloud host sales, or unrelated marketplace features.
@@ -0,0 +1,61 @@
+## 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
@@ -0,0 +1,46 @@
+## 1. Platform Bridge Execution Contracts
+
+- [x] 1.1 Add platform domain and DTO contracts for bridge execution requests, responses, result refs, and safe errors.
+- [x] 1.2 Add validators for action support, required permissions, page route scope, server scope, payload bounds, AI purposes, and unsafe path/secret/socket content.
+- [x] 1.3 Add service methods that authorize and execute supported bridge actions through existing platform services.
+
+## 2. Platform Bridge Execution API
+
+- [x] 2.1 Implement bridge execution route using named DTOs and service methods.
+- [x] 2.2 Map supported actions to safe service calls for server context, job dispatch, logs, artifacts, scoped files, and platform-mediated AI where available.
+- [x] 2.3 Update platform route/protocol documentation for plugin bridge execution and deferred unsupported actions.
+- [x] 2.4 Add platform tests for allowed execution, denied permissions, unsupported actions, unsafe payloads, safe errors, and no-secret responses.
+
+## 3. Frontend Host Execution
+
+- [x] 3.1 Add centralized frontend API types/client methods for bridge execution.
+- [x] 3.2 Add plugin page host session and request dispatcher utilities that construct safe context and return typed envelopes.
+- [x] 3.3 Update plugin page host UI flow to use bridge execution utilities for embedded plugin actions.
+- [x] 3.4 Add frontend tests for session safety, permission filtering, allowed dispatch, denied dispatch, cancellation/error states, and no raw secret rendering.
+
+## 4. Plugin SDK And Example
+
+- [x] 4.1 Extend plugin SDK helpers and example plugin page code to exercise bridge execution envelopes.
+- [x] 4.2 Add plugin tests for execution request builders, safe error parsing, and forbidden direct transport assumptions.
+
+## 5. Verification
+
+- [x] 5.1 Run `cd platform && go test ./...` and record evidence.
+- [x] 5.2 Run `cd platform_web && npm run typecheck && npm test && npm run build` and record evidence.
+- [x] 5.3 Run `cd plugins && npm run typecheck && npm test` and record evidence.
+- [x] 5.4 Run browser walkthrough for plugin page bridge execution and record evidence.
+- [x] 5.5 Run `scripts/check-structure.sh` and record evidence.
+- [x] 5.6 Run `openspec validate implement-plugin-page-bridge-execution --strict` and record evidence.
+
+## Evidence
+
+- 2026-07-06: `cd platform && GOCACHE=/private/tmp/browser-go-build-cache go test ./... -run TestPluginBridgeExecuteAPI -count=1` passed for bridge execution route, service mappings, safe errors, unsafe payload rejection, and no-secret response checks.
+- 2026-07-06: `cd platform_web && npm run typecheck` passed after adding bridge execution API types/client, host dispatcher, and server detail execution panel.
+- 2026-07-06: `cd platform_web && npm test -- --run utils/pluginBridgeHost.test.ts api/client.test.ts` passed, covering safe host context, permission filtering, allowed dispatch, unsafe/denied/cancelled states, and API client routing.
+- 2026-07-06: `cd plugins && npm run typecheck` and `cd plugins && npm test -- --run tests/manifest-validation.test.ts` passed for SDK execution envelope helpers and no direct transport assumptions.
+- 2026-07-06: `cd platform && GOCACHE=/private/tmp/browser-go-build-cache go test ./...` passed.
+- 2026-07-06: `cd platform_web && npm run typecheck`, `cd platform_web && npm test`, and `cd platform_web && npm run build` passed.
+- 2026-07-06: `cd plugins && npm run typecheck` and `cd plugins && npm test` passed.
+- 2026-07-06: Browser walkthrough passed using a local mock platform API plus headless Chrome: logged in, opened `#/servers/server-bridge-walkthrough`, switched to `插件控制`, clicked `读取上下文`, and verified `服务器上下文 server-bridge-walkthrough 已返回` with no forbidden fragments rendered.
+- 2026-07-06: `scripts/check-structure.sh` passed.
+- 2026-07-06: `openspec validate implement-plugin-page-bridge-execution --strict` passed (`Change 'implement-plugin-page-bridge-execution' is valid`; PostHog DNS flush warnings were non-fatal telemetry failures).