browser/openspec/changes/secure-single-file-run-distribution/specs/secure-single-file-run-distribution/spec.md

ADDED Requirements

Requirement: Platform publishes single-file Run executables

The platform SHALL publish Run distributions as one raw executable per server, target OS, and architecture instead of an archive containing a sidecar configuration file.

Scenario: Operator generates Windows Run

• WHEN an authorized operator generates Run for a Windows target
• THEN platform MUST queue a distribution build job that uploads a single executable artifact and presents it as run-windows-<arch>.exe with application/octet-stream
• AND the artifact MUST NOT contain a downloadable config.json sidecar

Scenario: Operator generates Linux Run

• WHEN an authorized operator generates Run for a Linux target
• THEN platform MUST queue a distribution build job that uploads a single executable artifact and presents it as run-linux-<arch> with application/octet-stream

Requirement: Run authorization is compiled into the executable

Run distribution builds SHALL inject server-scoped identity and the active Run authorization key into the executable at Go build time.

Scenario: Build input is consumed by trusted Run builder

• WHEN a Run worker receives authenticated distribution build input for component kind run
• THEN it MUST compile the target with Go -ldflags -X values for worker mode, platform URL, run endpoint ID, server instance ID, plugin ID, component kind, key generation, target release, and authorization token
• AND explicit runtime environment variables such as RUN_PLATFORM_URL MUST remain able to override compiled defaults for local development

Scenario: Compiled executable starts without sidecar config

• WHEN the generated Run executable starts with no config.json
• THEN it MUST load the compiled identity and key, register as a worker by default, and authenticate against the current platform key generation

Requirement: Run keys use increased entropy

Platform SHALL generate Run component keys with more entropy than general-purpose platform tokens while preserving existing global token behavior.

Scenario: Run key is created or reset

• WHEN platform creates or resets a Run component key
• THEN it MUST use a dedicated Run key generator of at least 64 random bytes before URL-safe encoding
• AND it MUST NOT change auth session or job lease token generation

Requirement: Raw executable self-update is supported

Run self-update SHALL accept raw executable artifacts for supported Run targets.

Scenario: Raw update artifact is staged

• WHEN Run receives a self-update job whose package format is raw-executable
• THEN Run MUST download the artifact through the artifact channel, verify the full checksum, stage it as an executable file, record the staged binary checksum, and use the existing activation/rollback flow

Scenario: Unsupported update package is requested

• WHEN Run receives a self-update job with an unsupported package format
• THEN Run MUST reject the update before activation and keep the current executable

Requirement: Server list exposes run-key reset

The server-list runtime action menu SHALL expose run-key reset as a destructive runtime operation when the platform reports it available.

Scenario: Operator resets from server list

• WHEN an authorized operator chooses run-key reset from the server-list 运行操作 menu and confirms the destructive action
• THEN platform_web MUST call the existing run-key reset API, show a tracked operation result, refresh server state, and indicate that a new Run executable must be generated

Requirement: Run key reset revokes active control sessions

Resetting a Run key SHALL immediately invalidate the active Run control session for the server's assigned Run endpoint.

Scenario: Online Run key is reset

• WHEN platform successfully resets the Run key for a server instance with an active Run control session
• THEN platform MUST remove that session so old deployed executables cannot continue heartbeat or job traffic under the stale key