admin343/browser
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(scum): declare protected run requests

Browse Source
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
Download Patch File Download Diff File Expand all files Collapse all files
openspec/changes/move-scum-feature-ownership-to-plugin/design.md
+22 -18
View File
@@ -1,29 +1,33 @@
## Design
The platform owns only reusable authorization, server isolation, auditing,
queues, opaque storage, and channels to Run. The SCUM plugin owns its page,
allowlists, schemas, event parsers, and Companion adapters. `platform_web`
mounts the declared plugin page generically.
The platform owns reusable authorization, tenant/server isolation, approvals,
auditing, expiry, queues, protected storage, and channels to Run. The SCUM
plugin owns its page, request generation, schemas, event parsers, and
Companion adapters. `platform_web` mounts the declared plugin page generically.
Run emits SCUM process stdout/stderr records through the durable log channel;
these are not server execution logs. The Companion parses only declared,
A bridge command may declare a protected request transport of kind `sql`,
`rcon`, or `program`. The declaration names only logical transport and target
keys plus a bounded text field; it cannot name a DSN, path, socket, credential,
or executable. A plugin can generate the request text, but Platform retains it
as protected payload, emits only redacted audit metadata, and forwards it only
after the normal server scope, permission, approval, expiry, and queue checks.
Run consumes a fenced, server-bound authorized request and resolves secrets and
the actual transport locally. Platform does not parse game-specific SQL, RCON,
or program syntax. `program` means a management-program transport accepted by
Run policy, never an operating-system shell.
Run emits SCUM process stdout/stderr console records through the durable log
channel; these are not file execution logs. The Companion parses only declared,
bounded record formats into semantic events. Unknown records make a bounded
diagnostic and are skipped. A per-server correlation digest may be derived
locally but never includes a raw network value in an upload.
The Companion receives only typed commands and invokes only registered typed
ports. Its game-data port exposes allowlisted player, vehicle, and position
data as bounded projections, never DSNs, paths, credentials, or rows. Fixed
server-management ports expose only declared operations. State changes read
the precondition, verify a safe window, write allowed fields, then confirm the
write. Reward delivery freezes a grant and maps each receipt to delivered,
failed, or unknown without retrying unknown outcomes. A command's failure or
unknown result affects that command alone.
The Companion receives only authorized, server-bound bridge commands and
bounded console records. Plugins, pages, and AI never receive DSNs, paths,
credentials, raw connections, sockets, or shell access. Run results are bounded
to `succeeded`, `failed`, or `unknown` with safe diagnostics. A request failure,
unknown text, or unsupported field affects that request alone.
Runtime capability/schema probes decide whether a particular handler is
available. They do not depend on a server/game/UE4SS/database version, build,
or source revision, and a failed probe never disables unrelated features.
`vehicle.spawn` is the one fixed administration template. It accepts only a
catalogued identifier and builds exactly `#spawnvehicle <vehicleCode>` inside
the Companion. The text stays private to its typed transport/audit boundary.
openspec/changes/move-scum-feature-ownership-to-plugin/implementation-blockers.md
+9 -6
View File
@@ -5,13 +5,16 @@ features are not disabled by an update string. The Companion uses typed,
platform-authorized non-production fixtures for configuration, player-state,
reward, notification, and vehicle operations; no remote server is contacted.
Run's required integration boundary is a bounded stdout/stderr record stream,
typed database projections, and fixed administration ports. It must not expose
paths, DSNs, credentials, raw rows, arbitrary SQL, shell, socket, or RCON to
the plugin, platform web, or AI. Unknown console formats create a bounded
diagnostic and no event.
Run's required integration boundary is a bounded stdout/stderr console record
stream and declared protected SQL, RCON, or management-program transports.
Plugins generate bounded request text, while Platform authorizes, approves,
queues, redacts, and forwards it only to the bound Run request. Run alone
resolves its local transport. Paths, DSNs, credentials, raw connections, host
paths, sockets, and host OS shell access never reach the plugin, platform web,
or AI. Unknown console or request formats create a bounded diagnostic for the
affected request and no fabricated event.
Remaining production enablement is operational: a deployed Run implementation
must provide the declared typed ports. Until then only the affected operation
must provide the declared protected transports. Until then only the affected operation
is reported unavailable; the plugin page and unrelated feature capabilities
remain active.
openspec/changes/move-scum-feature-ownership-to-plugin/ownership-audit.md
+2 -2
View File
@@ -8,8 +8,8 @@ plugin bundle and Companion channel.
| --- | --- | --- | --- |
| `api/game_player_handlers.go`, `service/game_players.go`, `domain/game_players.go` | SCUM player profiles, sessions, risk projections | `features/players` page data projected from declared `scum.login`/`scum.logout` semantic events | Companion parser and event uploader |
| `api/game_map_trajectory_handlers.go`, `service/game_map_trajectories.go`, `domain/game_map_trajectories.go` | SCUM map conversion and trajectory projection | `features/trajectories` catalog and page projection | A verified server-side source; otherwise the page remains unavailable |
| `api/game_gift_handlers.go`, `service/game_gifts.go`, `domain/game_gifts.go` | SCUM catalog, frozen revisions and grant workflow | `features/rewards` contracts plus `reward.deliver` and `player.notify` handlers | Compatible Companion reward handler and approved revision |
| `api/game_player_handlers.go`, `service/game_player_state_patch.go`, `domain/game_player_state_patch.go` | SCUM field catalog and state-patch approval | `features/state-patches` versioned field catalog and `game-state.patch` handler | Version discovery and verified safe window |
| `api/game_gift_handlers.go`, `service/game_gifts.go`, `domain/game_gifts.go` | SCUM catalog and grant workflow | `features/rewards` contracts plus declared protected request handlers | Available server-bound handler and approval |
| `api/game_player_handlers.go`, `service/game_player_state_patch.go`, `domain/game_player_state_patch.go` | SCUM field catalog and state-patch approval | `features/state-patches` declarative field catalog and protected request handler | Runtime schema availability and approval |
| `components/ScumFileConfigWorkbench.tsx` | SCUM configuration workbench | SCUM page bundle configuration catalog | Companion `config.read`/`config.patch` availability |
| `components/GamePlayerIntelligencePanel.tsx`, `GameGiftCatalogPanel.tsx`, `ScumMapTrajectoryPanel.tsx` | SCUM panels imported by the host | SCUM page bundle module | Generic manifest bundle validation and plugin-page host |
| `contracts/scumOperations.ts`, `schemas/scumOperations.ts` | `game.scum` host branch | manifest-driven bundle contract | Generic page-bundle registry |
openspec/changes/move-scum-feature-ownership-to-plugin/proposal.md
+21 -11
View File
@@ -2,22 +2,32 @@
SCUM plugin behavior must survive server updates without treating a game, UE4SS,
database, build, or revision string as a feature kill switch. The prior plan
incorrectly used static compatibility gates.
also incorrectly treated plugin-generated SQL and management-command text as a
direct-access surface. Generating text is distinct from possessing a DSN, RCON
credential, host path, socket, or shell capability.
## What Changes
- Move all SCUM feature authority to the plugin and its Companion, with generic
platform authorization, isolation, audit, queue, storage, and Run channels.
platform authorization, isolation, approval, audit, expiry, queue, protected
storage, and Run channels.
- Replace build/version/revision gates with runtime schema and capability probes.
- Let Run provide bounded SCUM stdout/stderr records, typed database reads, and
fixed administration operations only through platform-authorized channels.
- Require field allowlists, pre-read/safe-window/write-confirmation flows, and
`succeeded`/`failed`/`unknown` results for mutating adapters.
- Preserve fixed-template `vehicle.spawn`; its private `#spawnvehicle
<vehicleCode>` audit text never enters a result or page payload.
- Let plugins declare and generate bounded SQL, RCON, or program-management
request text for a logical, server-bound protected transport. Platform stores,
authorizes, approves, audits, expires, and forwards that opaque payload; Run
alone resolves the bound transport and executes the authorized request.
- Keep platform transport-agnostic: it validates declarations, scope, limits,
lifecycle, and redaction but does not parse SCUM SQL, RCON, or program syntax.
- Let Run provide bounded SCUM process stdout/stderr console records through the
platform log channel for plugin parsing. These are not file execution logs.
- Require bounded `succeeded`/`failed`/`unknown` result classifications and safe
diagnostics. Unknown text, command formats, and fields affect only the one
request and never disable unrelated features.
## Non-Goals
No arbitrary RCON, SQL, shell, socket, path, DSN, credential, raw database
row, OCR, screenshot, keyboard/mouse injection, or desktop automation is
introduced. No SCUM import or `game.scum` branch is added to `platform_web`.
No plugin, page, AI request, or result projection receives a DSN, database
path, raw connection, RCON credential, host path, direct socket, or shell.
Protected program-management requests are not host OS shell requests. No OCR,
screenshot, keyboard/mouse injection, desktop automation, Run source, SCUM
import, or `game.scum` branch is added to `platform_web`.
openspec/changes/move-scum-feature-ownership-to-plugin/specs/scum-companion-runtime-adapter/spec.md
+23 -30
View File
@@ -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
openspec/changes/move-scum-feature-ownership-to-plugin/specs/scum-plugin-feature-ownership/spec.md
+17 -1
View File
@@ -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
openspec/changes/move-scum-feature-ownership-to-plugin/tasks.md
+12 -17
View File
@@ -1,22 +1,17 @@
## 1. Replace version gates with runtime probes
## 1. Reopen the architecture boundary
- [x] 1.1 Remove SCUM/game/UE4SS/database build, revision, and version feature gates from the change contract, manifest-facing feature layer, Companion registry, adapters, and tests.
- [x] 1.2 Make handler availability server-bound and capability/schema-probe based; isolate failure to the affected command.
- [x] 1.1 Replace the prior SQL/RCON prohibition and fixed SCUM command template in proposal, design, and specifications with generic protected request semantics.
- [x] 1.2 Preserve runtime probe isolation while removing every SCUM/UE4SS/database build, revision, and version gate.
## 2. Establish typed Run/Companion boundaries
## 2. Define browser-side protected request contracts
- [x] 2.1 Define restricted typed ports for configuration, player state, rewards, notifications, and fixed server administration with no raw paths, DSNs, rows, credentials, SQL, shell, sockets, or RCON.
- [x] 2.2 Parse bounded Run stdout/stderr records into semantic events; skip unknown formats with bounded diagnostics and irreversible per-server correlation.
- [x] 2.3 Implement state pre-read, safe-window, allowlisted write, and read-after-write confirmation with typed results.
- [x] 2.4 Implement frozen typed reward delivery results without automatic unknown retries.
- [x] 2.5 Preserve the fixed private vehicle-spawn template and its allowlist.
- [x] 2.1 Add generic SQL, RCON, and management-program protected transport declarations to the manifest schema, platform domain validation, and plugin SDK.
- [x] 2.2 Permit only a declared bounded request-text field for protected commands; continue rejecting credentials, DSNs, paths, raw connections, direct sockets, and host OS shell material.
- [x] 2.3 Keep queue, approval, server/tenant isolation, expiry, and Run-facing protected payload semantics generic; redact text from browser responses and audit summaries.
- [x] 2.4 Declare SCUM plugin protected database and management transports without adding SCUM parsing or a fixed command template.
## 3. Complete plugin-owned migration
## 3. Verify and deliver
- [x] 3.1 Remove version-scoped feature catalogs, page context, API requests, and migration flags in favor of runtime schema/capability availability.
- [x] 3.2 Keep platform records read-only with provenance and leave platform-web generic.
## 4. Verify and deliver
- [x] 4.1 Run Companion, plugin, manifest, OpenSpec strict, structure, and scoped source-boundary verification.
- [x] 4.2 Stage scoped files, commit, and push `main`.
- [x] 3.1 Update focused Go and TypeScript tests for declarations, request generation, redaction, and safe rejection.
- [x] 3.2 Run focused Go/TS tests, OpenSpec strict validation, and structure verification.
- [ ] 3.3 Stage scoped files, commit, and push `main` (commit created; push remains blocked by remote SSH access).