Freeze SCUM typed RCON run contract

2026-08-13 13:37:37 +08:00
parent 467d5c3a8c
commit ac6f5419fe
17 changed files with 643 additions and 11 deletions
@@ -61,6 +61,11 @@ func ValidateRunJobResult(result domain.RunJobResult) error {
 			violations = append(violations, "executionResult.sqliteTemplate: "+err.Error())
 		}
 	}
+	if result.ExecutionResult.RCONTemplate != nil {
+		if err := ValidateSCUMTypedRCONTemplateResult(*result.ExecutionResult.RCONTemplate); err != nil {
+			violations = append(violations, "executionResult.rconTemplate: "+err.Error())
+		}
+	}
 	return finish(violations)
 }

@@ -1541,6 +1541,17 @@ func ValidateJob(job domain.Job) error {
 			violations = append(violations, "executionInput.sqliteTemplate is allowed only for sqlite query jobs")
 		}
 	}
+	if job.ExecutionInput.RCONTemplate != nil {
+		if err := ValidateSCUMTypedRCONTemplateRequest(*job.ExecutionInput.RCONTemplate); err != nil {
+			violations = append(violations, "executionInput.rconTemplate: "+err.Error())
+		}
+		if job.Capability != domain.JobCapabilityRemoteRunProtectedRCON {
+			violations = append(violations, "executionInput.rconTemplate is allowed only for protected rcon jobs")
+		}
+		if job.ExecutionInput.SourceRCON == nil || job.ExecutionInput.RemoteAdapterKind != "protected-rcon" {
+			violations = append(violations, "executionInput.rconTemplate requires a protected rcon transport plan")
+		}
+	}
 	violations = append(violations, validateRemoteAdapterInputs("executionInput.inputs", job.ExecutionInput.Inputs)...)
 	if job.ExecutionResult.Checksum != "" && !validSHA256Checksum(job.ExecutionResult.Checksum) {
 		violations = append(violations, "executionResult.checksum must be sha256:<hex>")
@@ -1561,6 +1572,11 @@ func ValidateJob(job domain.Job) error {
 			violations = append(violations, "executionResult.sqliteTemplate: "+err.Error())
 		}
 	}
+	if job.ExecutionResult.RCONTemplate != nil {
+		if err := ValidateSCUMTypedRCONTemplateResult(*job.ExecutionResult.RCONTemplate); err != nil {
+			violations = append(violations, "executionResult.rconTemplate: "+err.Error())
+		}
+	}
 	if job.Capability == domain.JobCapabilityConfigWrite || job.Capability == domain.JobCapabilityFilesRead || job.Capability == domain.JobCapabilityFilesWrite {
 		if job.ServerInstanceID == "" {
 			violations = append(violations, "serverInstanceId is required for scoped file jobs")
@@ -1,6 +1,7 @@
 package validator

 import (
+	"encoding/json"
 	"fmt"
 	"regexp"
 	"strings"
@@ -20,6 +21,9 @@ const (
 	maxSCUMTemplateRows          = 1000
 	maxSCUMTemplateBusyTimeoutMS = 1000
 	maxSCUMTemplateValueBytes    = 4096
+	maxSCUMRCONPayloadBytes      = 4096
+	maxSCUMRCONResponseBytes     = 64 * 1024
+	maxSCUMRCONConfirmRecords    = 128
 )

 var scumHashPattern = regexp.MustCompile(`^sha256:[a-fA-F0-9]{64}$|^[a-fA-F0-9]{16,128}$`)
@@ -66,6 +70,42 @@ func ValidateSCUMSQLiteTemplateRequest(request domain.SCUMSQLiteTemplateRequest)
 	return finish(violations)
 }

+func ValidateSCUMTypedRCONTemplateRequest(request domain.SCUMTypedRCONTemplateRequest) error {
+	var violations []string
+	violations = appendRequired(violations, "requestId", request.RequestID)
+	violations = appendRequired(violations, "jobId", request.JobID)
+	violations = append(violations, validateSCUMBindingIdentity("binding", request.Binding)...)
+	if !validSCUMRCONWriteCapability(request.Capability) {
+		violations = append(violations, "capability must be a typed RCON write capability")
+	}
+	violations = append(violations, validateSCUMTemplateKey("transportKey", request.TransportKey)...)
+	violations = append(violations, validateSCUMTemplateKey("targetKey", request.TargetKey)...)
+	violations = append(violations, validateSCUMTemplateKey("templateKey", request.TemplateKey)...)
+	violations = appendRequired(violations, "adapterVersion", request.AdapterVersion)
+	if request.AdapterVersion != "" && containsSCUMProtectedMaterial(request.AdapterVersion) {
+		violations = append(violations, "adapterVersion contains protected material")
+	}
+	if request.AdapterVersion != "" && request.Binding.AdapterVersion != "" && request.AdapterVersion != request.Binding.AdapterVersion {
+		violations = append(violations, "adapterVersion must match binding.adapterVersion")
+	}
+	if request.RequiredSchemaFingerprint != "" && !validSCUMFingerprint(request.RequiredSchemaFingerprint) {
+		violations = append(violations, "requiredSchemaFingerprint must be a digest/fingerprint")
+	}
+	for _, item := range []struct{ name, value string }{{"assetDigest", request.AssetDigest}, {"payloadDigest", request.PayloadDigest}, {"confirmationDigest", request.ConfirmationDigest}, {"targetIdentityDigest", request.TargetIdentityDigest}} {
+		if !validSCUMDigest(item.value) {
+			violations = append(violations, item.name+" must be sha256 digest")
+		}
+	}
+	violations = append(violations, validateSCUMTemplateKey("idempotencyKey", request.IdempotencyKey)...)
+	if strings.TrimSpace(request.ReviewReason) == "" || len(request.ReviewReason) > 320 || containsSCUMProtectedMaterial(request.ReviewReason) {
+		violations = append(violations, "reviewReason is unsafe")
+	}
+	violations = append(violations, validateSCUMTypedRCONTemplateBounds("bounds", request.Bounds)...)
+	violations = append(violations, validateSCUMValueMap("payload", request.Payload, 64)...)
+	violations = append(violations, validateSCUMJSONSize("payload", request.Payload, request.Bounds.MaxPayloadBytes)...)
+	return finish(violations)
+}
+
 func ValidateSCUMSchemaProbeResult(result domain.SCUMSchemaProbeResult) error {
 	var violations []string
 	violations = appendRequired(violations, "requestId", result.RequestID)
@@ -154,6 +194,62 @@ func ValidateSCUMSQLiteTemplateResult(result domain.SCUMSQLiteTemplateResult) er
 	return finish(violations)
 }

+func ValidateSCUMTypedRCONTemplateResult(result domain.SCUMTypedRCONTemplateResult) error {
+	var violations []string
+	violations = appendRequired(violations, "requestId", result.RequestID)
+	violations = appendRequired(violations, "jobId", result.JobID)
+	violations = append(violations, validateSCUMBindingIdentity("binding", result.Binding)...)
+	if !validSCUMTerminalResultStatus(result.Status) {
+		violations = append(violations, "status is invalid")
+	}
+	if !validSCUMRCONWriteCapability(result.Capability) {
+		violations = append(violations, "capability must be a typed RCON write capability")
+	}
+	violations = append(violations, validateSCUMTemplateKey("transportKey", result.TransportKey)...)
+	violations = append(violations, validateSCUMTemplateKey("targetKey", result.TargetKey)...)
+	violations = append(violations, validateSCUMTemplateKey("templateKey", result.TemplateKey)...)
+	violations = appendRequired(violations, "adapterVersion", result.AdapterVersion)
+	if result.AdapterVersion != "" && containsSCUMProtectedMaterial(result.AdapterVersion) {
+		violations = append(violations, "adapterVersion contains protected material")
+	}
+	if result.AdapterVersion != "" && result.Binding.AdapterVersion != "" && result.AdapterVersion != result.Binding.AdapterVersion {
+		violations = append(violations, "adapterVersion must match binding.adapterVersion")
+	}
+	if result.SchemaFingerprint != "" && !validSCUMFingerprint(result.SchemaFingerprint) {
+		violations = append(violations, "schemaFingerprint must be a digest/fingerprint")
+	}
+	for _, item := range []struct{ name, value string }{{"assetDigest", result.AssetDigest}, {"payloadDigest", result.PayloadDigest}, {"confirmationDigest", result.ConfirmationDigest}, {"targetIdentityDigest", result.TargetIdentityDigest}, {"resultDigest", result.ResultDigest}} {
+		if !validSCUMDigest(item.value) {
+			violations = append(violations, item.name+" must be sha256 digest")
+		}
+	}
+	if result.ResponseDigest != "" && !validSCUMDigest(result.ResponseDigest) {
+		violations = append(violations, "responseDigest must be sha256 digest")
+	}
+	if result.ConfirmationDigestID != "" && !validSCUMDigest(result.ConfirmationDigestID) {
+		violations = append(violations, "confirmationDigestId must be sha256 digest")
+	}
+	if !validSCUMRCONConfirmationStatus(result.ConfirmationStatus) {
+		violations = append(violations, "confirmationStatus is invalid")
+	}
+	if len(result.SafeSummary) > 320 || containsSCUMProtectedMaterial(result.SafeSummary) {
+		violations = append(violations, "safeSummary is unsafe")
+	}
+	violations = append(violations, validateSCUMSafeError("safeError", result.SafeError)...)
+	violations = append(violations, validateSCUMTypedRCONTemplateBounds("limits", result.Limits)...)
+	if result.Status == domain.SCUMTerminalResultSucceeded {
+		if result.ConfirmationStatus != domain.SCUMRCONConfirmationConfirmed || result.ResponseDigest == "" || result.ConfirmationDigestID == "" {
+			violations = append(violations, "succeeded result requires confirmed response and confirmation digests")
+		}
+		if result.SafeError.Code != "" && result.SafeError.Code != domain.SCUMSafeErrorNone {
+			violations = append(violations, "succeeded result must not carry an error code")
+		}
+	} else if result.SafeError.Code == "" || result.SafeError.Code == domain.SCUMSafeErrorNone {
+		violations = append(violations, "non-succeeded result requires a safe error code")
+	}
+	return finish(violations)
+}
+
 func ValidateSCUMCapabilityEvidence(evidence domain.SCUMCapabilityEvidence) error {
 	var violations []string
 	if !validSCUMDataCapability(evidence.Capability) {
@@ -328,10 +424,27 @@ func validateSCUMSQLiteTemplateBounds(prefix string, value domain.SCUMSQLiteTemp
 	return violations
 }

+func validateSCUMTypedRCONTemplateBounds(prefix string, value domain.SCUMTypedRCONTemplateBounds) []string {
+	var violations []string
+	if value.MaxPayloadBytes < 1 || value.MaxPayloadBytes > maxSCUMRCONPayloadBytes {
+		violations = append(violations, prefix+".maxPayloadBytes is out of bounds")
+	}
+	if value.TimeoutMS < 1 || value.TimeoutMS > maxSCUMProbeTimeoutMS {
+		violations = append(violations, prefix+".timeoutMs is out of bounds")
+	}
+	if value.MaxResponseBytes < 1 || value.MaxResponseBytes > maxSCUMRCONResponseBytes {
+		violations = append(violations, prefix+".maxResponseBytes is out of bounds")
+	}
+	if value.MaxConfirmRecords < 1 || value.MaxConfirmRecords > maxSCUMRCONConfirmRecords {
+		violations = append(violations, prefix+".maxConfirmRecords is out of bounds")
+	}
+	return violations
+}
+
 func validateSCUMTemplateKey(prefix, value string) []string {
 	var violations []string
 	violations = appendRequired(violations, prefix, value)
-	if value != "" && (!scumTemplateKeyPattern.MatchString(value) || containsSCUMProtectedMaterial(value) || strings.Contains(value, "..")) {
+	if value != "" && (!scumTemplateKeyPattern.MatchString(value) || strings.Contains(value, "..")) {
 		violations = append(violations, prefix+" is unsafe")
 	}
 	return violations
@@ -343,7 +456,8 @@ func validateSCUMValueMap(prefix string, values map[string]any, maxItems int) []
 		violations = append(violations, prefix+" exceeds declared limit")
 	}
 	for key, value := range values {
-		if !scumTemplateKeyPattern.MatchString(key) || containsSCUMProtectedMaterial(key) || strings.Contains(key, "..") {
+		loweredKey := strings.ToLower(key)
+		if !scumTemplateKeyPattern.MatchString(key) || containsSCUMProtectedMaterial(key) || strings.Contains(key, "..") || strings.Contains(loweredKey, "command") || strings.Contains(loweredKey, "rcon") {
 			violations = append(violations, prefix+" key is unsafe")
 		}
 		field := prefix + ".value"
@@ -370,6 +484,20 @@ func validateSCUMValue(prefix string, value any) []string {
 	return violations
 }

+func validateSCUMJSONSize(prefix string, value any, maxBytes int) []string {
+	if maxBytes <= 0 {
+		return []string{prefix + " max byte limit is required"}
+	}
+	payload, err := json.Marshal(value)
+	if err != nil {
+		return []string{prefix + " must be JSON serializable"}
+	}
+	if len(payload) > maxBytes {
+		return []string{prefix + " exceeds declared byte limit"}
+	}
+	return nil
+}
+
 func validateSCUMSchemaObjectEvidence(prefix string, value domain.SCUMSchemaObjectEvidence) []string {
 	var violations []string
 	if !validSCUMFingerprint(value.ObjectHash) {
@@ -449,6 +577,15 @@ func validSCUMReadCapability(value domain.SCUMDataCapability) bool {
 	}
 }

+func validSCUMRCONWriteCapability(value domain.SCUMDataCapability) bool {
+	switch value {
+	case domain.SCUMDataCapabilityEconomyCommand, domain.SCUMDataCapabilityGiftCommand:
+		return true
+	default:
+		return false
+	}
+}
+
 func validSCUMTerminalResultStatus(value domain.SCUMTerminalResultStatus) bool {
 	switch value {
 	case domain.SCUMTerminalResultSucceeded, domain.SCUMTerminalResultFailed, domain.SCUMTerminalResultCancelled:
@@ -458,6 +595,15 @@ func validSCUMTerminalResultStatus(value domain.SCUMTerminalResultStatus) bool {
 	}
 }

+func validSCUMRCONConfirmationStatus(value domain.SCUMRCONConfirmationStatus) bool {
+	switch value {
+	case domain.SCUMRCONConfirmationConfirmed, domain.SCUMRCONConfirmationFailed, domain.SCUMRCONConfirmationUnknown:
+		return true
+	default:
+		return false
+	}
+}
+
 func validSCUMCapabilityEvidenceStatus(value domain.SCUMCapabilityEvidenceStatus) bool {
 	switch value {
 	case domain.SCUMCapabilityEvidenceMissing, domain.SCUMCapabilityEvidenceCompatible, domain.SCUMCapabilityEvidenceIncompatible, domain.SCUMCapabilityEvidenceFailed:
@@ -505,7 +651,7 @@ func containsSCUMProtectedMaterial(value string) bool {
 	if strings.HasPrefix(lowered, "sqlite://") || strings.HasPrefix(lowered, "mysql://") || strings.HasPrefix(lowered, "file://") || strings.HasPrefix(lowered, "tcp://") || strings.HasPrefix(lowered, "unix://") {
 		return true
 	}
-	if strings.HasPrefix(trimmed, "/") || strings.HasPrefix(trimmed, "\\\\") || regexp.MustCompile(`^[A-Za-z]:[\\/]`).MatchString(trimmed) {
+	if strings.HasPrefix(trimmed, "/") || strings.HasPrefix(trimmed, "\\\\") || regexp.MustCompile(`[A-Za-z]:[\\/]`).MatchString(trimmed) {
 		return true
 	}
 	return false
@@ -124,6 +124,45 @@ func TestValidateSCUMSQLiteTemplateResultRejectsUnsafeRowsAndMismatchedCounts(t
 	}
 }

+func TestValidateSCUMTypedRCONTemplateRequestAllowsBoundedGenericTemplate(t *testing.T) {
+	request := validatorSCUMTypedRCONTemplateRequest()
+
+	if err := ValidateSCUMTypedRCONTemplateRequest(request); err != nil {
+		t.Fatalf("expected valid typed RCON template request, got %v", err)
+	}
+}
+
+func TestValidateSCUMTypedRCONTemplateRequestRejectsRawCommandAndLooseBounds(t *testing.T) {
+	request := validatorSCUMTypedRCONTemplateRequest()
+	request.Payload = map[string]any{"rawCommand": "#SetFamePoints 7 100"}
+	request.ReviewReason = `use C:\SCUM\secret.txt`
+	request.Bounds.MaxPayloadBytes = 100000
+
+	err := ValidateSCUMTypedRCONTemplateRequest(request)
+	if err == nil || !strings.Contains(err.Error(), "payload key is unsafe") || !strings.Contains(err.Error(), "reviewReason is unsafe") || !strings.Contains(err.Error(), "maxPayloadBytes") {
+		t.Fatalf("expected raw command/reason/bounds violations, got %v", err)
+	}
+}
+
+func TestValidateSCUMTypedRCONTemplateResultAcceptsConfirmedEnvelope(t *testing.T) {
+	result := validatorSCUMTypedRCONTemplateResult()
+
+	if err := ValidateSCUMTypedRCONTemplateResult(result); err != nil {
+		t.Fatalf("expected valid typed RCON template result, got %v", err)
+	}
+}
+
+func TestValidateSCUMTypedRCONTemplateResultRejectsUnconfirmedSuccessAndUnsafeSummary(t *testing.T) {
+	result := validatorSCUMTypedRCONTemplateResult()
+	result.ConfirmationStatus = domain.SCUMRCONConfirmationUnknown
+	result.SafeSummary = "rcon password leaked"
+
+	err := ValidateSCUMTypedRCONTemplateResult(result)
+	if err == nil || !strings.Contains(err.Error(), "confirmed") || !strings.Contains(err.Error(), "safeSummary") {
+		t.Fatalf("expected confirmation and summary violations, got %v", err)
+	}
+}
+
 func TestValidateSCUMCapabilityEvidenceRequiresSafeCurrentServiceIdentity(t *testing.T) {
 	evidence := domain.SCUMCapabilityEvidence{Capability: domain.SCUMDataCapabilityPlayerRead, Status: domain.SCUMCapabilityEvidenceCompatible, Binding: validatorSCUMBinding(), AdapterVersion: "adapter-1", SchemaFingerprint: scumProbeHash, ProbeResultDigest: scumProbeHash, AssetDigests: []string{scumProbeHash}, SafeError: domain.SCUMSafeError{Code: domain.SCUMSafeErrorNone}}
 	if err := ValidateSCUMCapabilityEvidence(evidence); err != nil {
@@ -148,3 +187,12 @@ func validatorSCUMSQLiteTemplateResult() domain.SCUMSQLiteTemplateResult {
 	request := validatorSCUMSQLiteTemplateRequest()
 	return domain.SCUMSQLiteTemplateResult{RequestID: request.RequestID, JobID: request.JobID, Binding: request.Binding, Status: domain.SCUMTerminalResultSucceeded, Capability: request.Capability, TargetKey: request.TargetKey, TemplateKey: request.TemplateKey, AdapterVersion: request.AdapterVersion, SchemaFingerprint: request.RequiredSchemaFingerprint, AssetDigest: request.AssetDigest, ParameterDigest: request.ParameterDigest, SourceFingerprint: scumProbeHash, ObservedAt: time.Now(), ResultDigest: scumProbeHash, RowCount: 1, Rows: []map[string]any{{"externalPlayerId": "player-redacted", "displayName": "Known Player", "fame": 12.5, "online": true, "squadId": nil}}, Limits: request.Bounds, SafeError: domain.SCUMSafeError{Code: domain.SCUMSafeErrorNone}}
 }
+
+func validatorSCUMTypedRCONTemplateRequest() domain.SCUMTypedRCONTemplateRequest {
+	return domain.SCUMTypedRCONTemplateRequest{RequestID: "request-rcon-1", JobID: "job-rcon-1", Binding: validatorSCUMBinding(), Capability: domain.SCUMDataCapabilityEconomyCommand, TransportKey: "scum-rcon", TargetKey: "scum-rcon", TemplateKey: "economy.fame.set.v1", AdapterVersion: "adapter-1", RequiredSchemaFingerprint: scumProbeHash, AssetDigest: scumProbeHash, PayloadDigest: scumProbeHash, ConfirmationDigest: scumProbeHash, TargetIdentityDigest: scumProbeHash, IdempotencyKey: "idem-rcon-1", Payload: map[string]any{"externalPlayerId": "player-redacted", "absoluteValue": 100.0}, ReviewReason: "operator reviewed absolute fame update", Bounds: domain.DefaultSCUMTypedRCONTemplateBounds(), RequestedAt: time.Now()}
+}
+
+func validatorSCUMTypedRCONTemplateResult() domain.SCUMTypedRCONTemplateResult {
+	request := validatorSCUMTypedRCONTemplateRequest()
+	return domain.SCUMTypedRCONTemplateResult{RequestID: request.RequestID, JobID: request.JobID, Binding: request.Binding, Status: domain.SCUMTerminalResultSucceeded, Capability: request.Capability, TransportKey: request.TransportKey, TargetKey: request.TargetKey, TemplateKey: request.TemplateKey, AdapterVersion: request.AdapterVersion, SchemaFingerprint: request.RequiredSchemaFingerprint, AssetDigest: request.AssetDigest, PayloadDigest: request.PayloadDigest, ConfirmationDigest: request.ConfirmationDigest, TargetIdentityDigest: request.TargetIdentityDigest, ObservedAt: time.Now(), ResultDigest: scumProbeHash, ResponseDigest: scumProbeHash, ConfirmationStatus: domain.SCUMRCONConfirmationConfirmed, ConfirmationDigestID: scumProbeHash, SafeSummary: "confirmed by declared readback", Limits: request.Bounds, SafeError: domain.SCUMSafeError{Code: domain.SCUMSafeErrorNone}}
+}