Add SCUM Source RCON transport

2026-07-23 10:55:31 +08:00
parent ec96c22e4c
commit 742f96ea02
33 changed files with 1297 additions and 19 deletions
@@ -0,0 +1,26 @@
+## ADDED Requirements
+
+### Requirement: Run executes a frozen Source RCON plan over loopback
+Run SHALL execute a `source-rcon` plan only for Windows amd64 and only by dialing `127.0.0.1` at the frozen declared port. It SHALL resolve the plan's generated config through the scoped workspace, read the protected password locally, and use Source RCON authentication and framed command/response packets. It SHALL not accept a browser-provided host, socket, path, or password.
+
+#### Scenario: Valid loopback Source RCON command completes
+- **WHEN** Run receives a valid frozen plan and one-time command for a running compatible SCUM server
+- **THEN** it authenticates to the local DLL listener, sends the command, consumes the terminal response sentinel, and completes the job with a safe success status.
+
+#### Scenario: Unsafe plan or local configuration is rejected
+- **WHEN** a plan is not `source-rcon`, is non-Windows, has an unsafe config key/port, or the local config is missing, non-loopback, or inconsistent with the frozen port
+- **THEN** Run fails before opening a socket or sending a command.
+
+### Requirement: Run bounds and redacts Source RCON I/O
+Run SHALL bound command bytes, packet sizes, response bytes, response packet count, dialing, authentication, and command execution by the job context. It SHALL classify an RCON error response as a failed job but SHALL NOT persist or return the raw command, password, response body, config contents, or local path in logs, artifacts, progress, or result messages.
+
+#### Scenario: Source RCON error response remains private
+- **WHEN** the DLL returns an `error:` response or malformed response framing
+- **THEN** Run returns a safe error code/message without exposing the returned body or submitted command.
+
+### Requirement: Source RCON transport is at-most-once
+Run SHALL retrieve the command from the active Platform input route once per job and SHALL not retry a command after input, authentication, dial, or response failure. It SHALL not fall back to the placeholder remote adapter, a generic TCP address, `rundll32`, process injection, or a Linux loader.
+
+#### Scenario: Lost one-time input does not replay a command
+- **WHEN** Run cannot retrieve a fresh one-time command or loses execution after it was consumed
+- **THEN** it fails the job safely and does not send a duplicate command.
@@ -0,0 +1,37 @@
+## ADDED Requirements
+
+### Requirement: Platform dispatches a typed SCUM Source RCON command
+Platform SHALL accept a server-authorized typed request for either a SCUM chat message or a bounded raw SCUM command only when the installed plugin declares `remote.run.rcon.command`, the selected runtime profile declares the RCON transport, the endpoint reports the capability, and a selected ready Windows amd64 UE4SS DLL extension provides the Source RCON plan. Chat requests SHALL validate a type from 0 through 7, 1–1024 UTF-8 message bytes, and an optional 17-digit SteamID64 before Platform formats the DLL-supported `SendChat` command. Raw commands SHALL be non-empty UTF-8, contain no NUL/newline control framing, and fit within the declared Source RCON packet bound.
+
+#### Scenario: Authorized chat dispatch is queued
+- **WHEN** an authorized operator submits a valid broadcast or targeted chat request for a compatible ready SCUM server
+- **THEN** Platform creates one scoped `remote.run.rcon.command` job with a frozen Source RCON plan and returns only safe queued state.
+
+#### Scenario: Unsupported command request is rejected before dispatch
+- **WHEN** a request has malformed chat data, an unsafe raw command, an undeclared RCON capability, an unpublished extension, or a non-Windows endpoint
+- **THEN** Platform rejects it without creating a job or retaining command text.
+
+### Requirement: Raw RCON input is transient and one-time
+Platform SHALL hold raw RCON command text only in a bounded in-memory one-time broker keyed by the dispatch job. The persisted job, job assignment, browser DTOs, audit events, and result messages SHALL omit command text, chat text, source responses, host paths, and RCON credentials. RCON command jobs SHALL have one attempt and SHALL not automatically retry.
+
+#### Scenario: Active Run lease consumes a command once
+- **WHEN** the active leased Run attempt requests its RCON input
+- **THEN** Platform returns the command once and removes it from the broker.
+
+#### Scenario: Repeated, expired, or restarted delivery fails closed
+- **WHEN** a broker payload was already consumed, expired, or lost after a Platform restart
+- **THEN** a later Run input request fails safely and does not replay the command.
+
+### Requirement: Only the active signed Run attempt receives RCON input
+Platform SHALL expose RCON command input only through a signed Run-only route after validating the endpoint, session, job ID, lease token, attempt, scoped server, RCON capability, and frozen Source RCON plan. Browser and plugin APIs SHALL never receive the RCON input, password, host address, or generated local config path.
+
+#### Scenario: Stale or foreign lease cannot read a command
+- **WHEN** a Run input request has a wrong endpoint, session, lease token, attempt, or job capability
+- **THEN** Platform denies it and leaves a valid unconsumed broker payload intact.
+
+### Requirement: Management console provides direct chat and command controls
+The server management surface SHALL render direct chat and raw-command controls only through the typed Platform API. It SHALL not request a secondary confirmation, retain a command transcript, expose RCON connection material, or show raw Source RCON replies.
+
+#### Scenario: Console sends a chat without creating history
+- **WHEN** an authorized operator submits a valid chat form
+- **THEN** the console displays the safe dispatch status and does not render the chat text as a durable command record.