refactor(scum): declare protected run requests

This commit is contained in:
npc0-hue
2026-07-29 22:37:16 +08:00
parent d7465bfd32
commit 99be8f0f3a
28 changed files with 497 additions and 152 deletions
@@ -13,40 +13,33 @@ A probe or command failure SHALL affect only that handler invocation.
- **THEN** the Companion returns a typed unavailable/failed/unknown result for
that command and does not disable an unrelated plugin feature
### Requirement: Run data channels are bounded
### Requirement: Protected requests are platform mediated
Run SHALL send SCUM stdout/stderr records to the Companion through the durable
log channel and SHALL provide database data only as typed allowlisted
projections and fixed server-management operations. No plugin, web page, or
AI request SHALL receive a path, DSN, credential, raw row, arbitrary SQL,
shell, socket, or RCON command.
The SCUM plugin SHALL be able to generate bounded SQL, RCON, or
program-management request text for a declared logical protected transport.
Platform SHALL authorize, isolate by tenant and server, approve, audit with
redaction, expire, queue, store, and forward each opaque request to the bound
Run endpoint. Platform SHALL not parse SCUM SQL, RCON, or program syntax. Run
SHALL execute only a current, authorized, server-bound request and return a
bounded `succeeded`, `failed`, or `unknown` result with safe diagnostics.
No plugin, web page, or AI request SHALL receive a path, DSN, raw connection,
credential, host path, direct socket, or shell capability.
#### Scenario: Unsupported request format
- **WHEN** Run cannot recognize a request text, command format, or field
- **THEN** it returns `failed` or `unknown` with a safe diagnostic for that
request and does not disable an unrelated capability
### Requirement: SCUM console records use the log channel
Run SHALL send bounded SCUM process stdout/stderr console records through the
durable platform log channel. The Companion SHALL parse only declared bounded
formats and skip unknown lines with a bounded diagnostic. Console records are
not file execution logs.
#### Scenario: Unknown console output
- **WHEN** stdout or stderr does not match a declared semantic parser
- **THEN** the Companion records a bounded diagnostic and uploads no semantic
event or raw line
### Requirement: Mutations prove safety
State patch adapters SHALL use field allowlists, a pre-read, safe-window
verification, a bounded write, and read-after-write confirmation. Reward
adapters SHALL freeze their typed grant and return delivered, failed, or
unknown without automatically retrying unknown outcomes.
#### Scenario: Confirmation cannot be established
- **WHEN** a typed write or post-write read cannot establish success
- **THEN** the Companion returns `unknown` and does not repeat the operation
### Requirement: Vehicle spawning remains fixed
`vehicle.spawn` SHALL accept only a catalogued vehicle code and create exactly
`#spawnvehicle <vehicleCode>` inside the Companion. Protected audit text SHALL
not be present in command results or browser payloads.
#### Scenario: Unsafe spawn input
- **WHEN** input includes an unlisted code, an extra field, command text, SQL,
a path, credential, socket, shell text, or RCON text
- **THEN** no transport call occurs and validation fails
@@ -4,7 +4,8 @@
The SCUM plugin SHALL own SCUM schemas, allowlists, migration adapters,
Companion behavior, and feature UI. The platform SHALL retain only reusable
authorization, isolation, auditing, queues, storage, and generic plugin-host
authorization, isolation, approval, auditing, expiry, queues, protected
storage, generic Run transport declarations, and generic plugin-host
primitives. `platform_web` SHALL not import SCUM code or branch on `game.scum`.
#### Scenario: Page mounting
@@ -35,3 +36,18 @@ to the server and feature, never to a game version.
- **WHEN** no unique server-feature migration flag is present
- **THEN** historical records remain readable and plugin writes stay disabled
### Requirement: Protected request declarations are generic
The plugin manifest and SDK SHALL support generic declared protected request
transports for SQL, RCON, and management-program text. Declarations SHALL use
only logical server-bound transport/target keys and bounded text fields.
Browser projections and audit records SHALL redact request text. Declarations
shall not grant credentials, paths, raw connections, direct sockets, or host OS
shell execution.
#### Scenario: Plugin generates an SQL request
- **WHEN** the plugin queues SQL text through a declared protected transport
- **THEN** Platform stores and audits only its protected/redacted form and
forwards it only after generic authorization and approval checks