feat: reveal saved server deployment inputs

2026-07-27 09:24:44 +08:00
parent e5c94be1db
commit 6c5b74b915
19 changed files with 345 additions and 31 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-26
@@ -0,0 +1,40 @@
+## Context
+
+Platform persists each server's deployment definition, including host paths and lifecycle commands. The normal deployment endpoint intentionally exposes only configured flags, so the editor starts these fields blank. This protects operational data in ordinary reads but prevents an authorized operator from comparing the saved definition with Run behavior.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Let an authorized server manager explicitly retrieve and inspect that server's saved deployment inputs.
+- Make the editor visibly require this explicit action before it receives raw values.
+- Preserve redaction on all existing read projections.
+- Expose a safe indication of the latest lifecycle job's deployed revision and whether its leased input contained a deployment definition.
+
+**Non-Goals:**
+
+- No host browsing, direct Run connection, log changes, secret exposure, or changes to the Run protocol.
+- No display of runtime-binding credentials.
+- No attempt to infer what a previous Run process actually executed from Platform alone.
+
+## Decisions
+
+1. Add a separate authenticated `GET /server-instances/{id}/deployment/reveal` endpoint rather than expanding the existing deployment read response. This makes the security-sensitive action explicit and preserves compatibility for all existing consumers.
+2. Reuse server-owner authorization and return only the persisted path/command fields plus non-sensitive deployment metadata. Runtime bindings are excluded because they can contain credential references or secrets.
+3. Add a reveal button to the edit workflow. It calls the endpoint only after operator intent, replaces the local blank fields, and provides a clear success/error state. A plain close/reopen returns to the normal redacted form.
+4. Derive dispatch diagnostics from the current server's lifecycle jobs. It reports revision and deployment-input presence, not the leased fields themselves. Platform can prove a job was queued with the stored revision; only Run's own safe job result can prove successful execution.
+
+## Risks / Trade-offs
+
+- [An authorized browser session can now read operational paths/commands] → The sensitive response requires explicit owner-authorized access, is not cached in existing list/detail endpoints, and the UI fetches it only after an intentional action.
+- [Operators could confuse queued dispatch with successful execution] → Label the diagnostic as dispatch evidence and separately retain Run job state/progress.
+- [Sensitive values could linger in a browser tab] → Keep them only in the open workflow state and clear them when the dialog closes.
+
+## Migration Plan
+
+1. Deploy the additive endpoint and frontend reveal action.
+2. Roll back by removing the reveal route/UI; existing saved deployment definitions and normal redacted reads remain unchanged.
+
+## Open Questions
+
+- None. The requested scope is explicit authorized display of existing deployment values.
@@ -0,0 +1,27 @@
+## Why
+
+Operators cannot inspect the exact protected deployment paths and commands that Platform will send to Run. The current configured-only editor makes it impossible to verify an existing deployment or investigate whether Run used the intended inputs.
+
+## What Changes
+
+- Add an authorized, explicit read path for a server manager to reveal that server's saved deployment inputs.
+- Prefill the deployment editor from this reveal path only after the operator deliberately asks to show the configuration.
+- Keep ordinary deployment reads, server lists, job summaries, logs, audits, and plugin-facing reads redacted.
+- Add a safe deployment-input diagnostic that proves whether the Platform job dispatched to Run carried the saved deployment revision without putting raw values into job/status views.
+
+## Capabilities
+
+### New Capabilities
+
+- `server-deployment-input-reveal`: Authorized, explicit inspection of a server's saved deployment inputs and their Run-dispatch state.
+
+### Modified Capabilities
+
+- None.
+
+## Impact
+
+- Affected API: server deployment routes and DTOs.
+- Affected platform code: deployment service, repository-backed deployment data, lifecycle dispatch diagnostics, and API tests.
+- Affected frontend: the shared server deployment workflow and API types/client.
+- Affected external integration: Run job-input verification remains based on the existing leased deployment contract; no Run source or protocol expansion is required.
@@ -0,0 +1,37 @@
+## ADDED Requirements
+
+### Requirement: Authorized deployment input reveal
+The Platform SHALL provide an explicit authenticated read operation that lets an authorized server manager retrieve the saved server root, working directory, install command, start command, stop command, and status command for one server deployment. The operation MUST NOT return runtime bindings.
+
+#### Scenario: Owner reveals a custom deployment
+- **WHEN** an authorized server manager explicitly requests deployment input reveal for a stopped server with saved custom commands
+- **THEN** the Platform returns the saved deployment paths and commands for that server only
+
+#### Scenario: Unauthorized user requests reveal
+- **WHEN** a user without access to the server requests deployment input reveal
+- **THEN** the Platform rejects the request and returns no deployment input
+
+### Requirement: Default deployment views remain redacted
+The existing server deployment read endpoint and all list, detail, job, audit, log, and plugin-facing projections SHALL remain redacted after reveal support is added.
+
+#### Scenario: Normal deployment read after reveal support
+- **WHEN** an authorized user reads a configured deployment through the existing deployment endpoint
+- **THEN** the response indicates configured state without returning paths or commands
+
+### Requirement: Editor reveal is deliberate and bounded
+The deployment editor SHALL start with protected inputs redacted and SHALL fetch saved path and command values only after the operator selects its explicit reveal control. Closing the editor MUST discard revealed values from its local form state.
+
+#### Scenario: Operator opens editor without revealing
+- **WHEN** an operator opens an existing deployment editor
+- **THEN** protected input fields remain blank and show their configured state
+
+#### Scenario: Operator explicitly reveals inputs
+- **WHEN** an operator selects the reveal control in the open deployment editor
+- **THEN** the editor displays the returned saved paths and commands for inspection and editing
+
+### Requirement: Dispatch diagnostics distinguish Platform dispatch from Run execution
+The deployment view SHALL expose safe diagnostic metadata for the most recent lifecycle job: job identifier, job state, deployed revision, and whether the leased input included a deployment definition. It MUST NOT expose the leased values.
+
+#### Scenario: Platform queued a deployment definition
+- **WHEN** Platform creates a lifecycle job from a saved deployment definition
+- **THEN** the deployment diagnostic identifies the job revision and that the job included a deployment definition without returning its paths or commands
@@ -0,0 +1,22 @@
+## 任务提示
+
+- 正向提示词：为“服务器管理”提供已授权管理者主动查看和编辑已保存部署路径/命令的能力，并显示不泄露原文的 Platform→Run 调度证据。成功标准是显式展示可用、常规读取仍脱敏、测试可证明授权和调度行为。
+- 方向提示词：在 `platform/` 增加受限 reveal DTO、路由、服务和测试；在 `platform_web/` 的既有 `ServerDeploymentWorkflow` 内增加显式展示控件，复用现有控制台样式。验证运行 Go/前端测试、`openspec validate --strict` 和 `scripts/check-structure.sh`。
+- 任务边界：不修改独立 `run/` 源码或协议；不增加 SSH、主机浏览、日志/审计原文泄露、插件访问或运行绑定凭据展示；不触及未相关根目录或既有用户改动。
+
+## 1. Platform reveal and dispatch diagnostics
+
+- [x] 1.1 Define reveal and safe dispatch-diagnostic domain/DTO contracts, then add the authorized reveal endpoint without changing existing redacted views.
+- [x] 1.2 Derive safe latest-lifecycle-job dispatch evidence from the stored job record and include it in the normal deployment view.
+- [x] 1.3 Add service/API tests for owner reveal, unauthorized denial, existing-view redaction, and dispatched deployment evidence.
+
+## 2. Deployment editor reveal
+
+- [x] 2.1 Add API client/types for the explicit reveal operation and safe dispatch diagnostic.
+- [x] 2.2 Add an intentional reveal control to the shared deployment editor, populate returned fields, and clear the displayed values when it closes.
+- [x] 2.3 Add frontend tests that retain the normal redacted opening state and cover explicit reveal behavior.
+
+## 3. Verification
+
+- [x] 3.1 Run focused backend and frontend validation, strict OpenSpec validation, and the repository structure check.
+- [x] 3.2 Inspect the active Platform metadata and lifecycle-job evidence to report whether Run received the saved deployment definition without exposing raw values in the report.