feat: add UE4SS DLL runtime extension

2026-07-23 09:49:14 +08:00
parent 8e34c8762a
commit 1caf40565c
30 changed files with 1179 additions and 70 deletions
@@ -0,0 +1,34 @@
+## ADDED Requirements
+
+### Requirement: Plugin declares a bounded Windows UE4SS DLL extension
+The plugin manifest SHALL support `runtimeProfiles.dllExtensions` entries only for a fixed `ue4ss-dll` kind, Windows amd64 target, `server-start` activation, logical target key, declared DLL relative path, and update-on-start policy. A `ready` release SHALL additionally have an HTTPS release URL, SHA-256 checksum, bounded byte size, SCUM executable checksum, and UE4SS ABI marker. An `unpublished` declaration MAY document an intended release URL but SHALL not be frozen into a start job. The manifest validator SHALL reject executable references, shell arguments, Linux targets, unsafe URLs, non-DLL paths, missing ready-release integrity metadata, and unsafe logical keys.
+
+#### Scenario: Valid SCUM DLL declaration registers
+- **WHEN** `game.scum` registers a Windows UE4SS DLL extension with all required immutable release and compatibility fields
+- **THEN** Platform persists a typed declaration and exposes only a safe projection to browser clients.
+
+#### Scenario: Unsafe DLL declaration is rejected
+- **WHEN** a manifest declares a non-HTTPS URL, missing checksum, Linux target, executable command, unsafe path, or missing compatibility checksum
+- **THEN** manifest validation rejects the registration before it is persisted.
+
+#### Scenario: Unpublished SCUM release stays inactive
+- **WHEN** a plugin documents an unpublished UE4SS DLL release before the publisher has supplied its immutable release pins
+- **THEN** the declaration is safe to display but cannot be referenced by a server-start lifecycle profile or dispatched to Run.
+
+### Requirement: Server start freezes the declared extension plan
+Platform SHALL add the selected compatible DLL extension plan to the fenced `process.start` Run job input. The frozen plan SHALL contain only logical target identifiers and release integrity/compatibility metadata, and SHALL reject a start when the selected runtime profile or endpoint platform does not support the extension.
+
+#### Scenario: Compatible Windows server start includes extension plan
+- **WHEN** a Windows amd64 SCUM server with a selected compatible runtime profile is started
+- **THEN** its Run start job includes the current immutable DLL extension plan before process execution.
+
+#### Scenario: Linux server is rejected without a download
+- **WHEN** a Linux endpoint is selected for a UE4SS DLL extension profile
+- **THEN** Platform rejects the extension path with an explicit unsupported-platform result and does not dispatch a DLL download.
+
+### Requirement: Browser receives a safe extension projection
+Platform SHALL project extension key, display name, release version, checksum prefix, supported OS/architecture, loading mode, update-on-start policy, compatibility marker, and safe synchronization state to plugin and server management views. It SHALL NOT project RCON passwords, raw host paths, signed Run job data, native signatures, or raw local file metadata.
+
+#### Scenario: Server detail renders declaration without secrets
+- **WHEN** an authorized operator views a SCUM plugin or server detail
+- **THEN** the UI displays safe DLL extension metadata and does not contain credentials, host paths, or native resolver data.
@@ -0,0 +1,33 @@
+## ADDED Requirements
+
+### Requirement: Run synchronizes a frozen DLL plan before server start
+Run SHALL synchronize a declared UE4SS DLL extension before executing the associated `process.start` command. It SHALL compare the local managed-release marker against the frozen version/checksum, skip unchanged releases, and otherwise download, checksum-verify, stage, and atomically activate the declared DLL path within the scoped server workspace.
+
+#### Scenario: Changed approved DLL updates before launch
+- **WHEN** a start job carries a valid extension plan whose release differs from the managed marker
+- **THEN** Run verifies and activates the new DLL before launching the server process.
+
+#### Scenario: Unchanged approved DLL is reused
+- **WHEN** a start job carries the same version and checksum as the managed marker
+- **THEN** Run does not download the DLL again and proceeds to server launch.
+
+### Requirement: Run preserves DLL deployment safety boundaries
+Run SHALL require HTTPS, a SHA-256 checksum, bounded content length, a safe logical target, and a declared `.dll` path. It SHALL write only managed extension files, retain one previous DLL for rollback, redact sensitive generated configuration, and never execute the DLL, inject a running process, load arbitrary libraries, or expose raw local paths/credentials through Platform-facing results.
+
+#### Scenario: Invalid or mismatched payload does not activate
+- **WHEN** download fails, exceeds its byte limit, has a checksum mismatch, or the declared DLL path is unsafe
+- **THEN** Run keeps the prior managed DLL intact and returns a safe failed start result.
+
+### Requirement: Run explicitly rejects Linux UE4SS DLL activation
+Run SHALL reject a `ue4ss-dll` extension plan when its local platform is not Windows amd64. It SHALL not attempt to map the DLL, invoke a shell loader, or substitute `LD_PRELOAD`.
+
+#### Scenario: Linux extension start fails closed
+- **WHEN** a Linux Run receives a UE4SS DLL extension plan
+- **THEN** it returns `unsupported_extension_platform` before any download or process launch.
+
+### Requirement: Extension synchronization does not block independent channels
+DLL download and verification SHALL run inside the claimed lifecycle job with bounded context while Run control heartbeat, job acknowledgement/result, cancellation polling, log spool upload, and artifact transfer remain independently scheduled.
+
+#### Scenario: Slow DLL download preserves control and log traffic
+- **WHEN** a DLL download is blocked or slow during a start job
+- **THEN** Run continues its control heartbeat and durable log upload within their configured deadlines.