@opensoha/contracts 0.1.29 → 0.2.0

package/agent/environment/mcp_stdio.go

@@ -0,0 +1,30 @@
+package environment
+
+import (
+	"errors"
+	"regexp"
+)
+
+const PersonalMCPStdioHeader = "X-Soha-MCP-Environment"
+
+var personalMCPAssetID = regexp.MustCompile(`^[a-z0-9][a-z0-9-]{0,47}$`)
+var personalMCPVersion = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$`)
+
+// PersonalMCPStdioRequest binds a registered command to the original owner
+// lease. Neither the caller nor the model supplies a command or Docker ID.
+type PersonalMCPStdioRequest struct {
+	Lease   Lease  `json:"lease"`
+	AssetID string `json:"assetId"`
+	Version string `json:"version"`
+}
+
+func (r PersonalMCPStdioRequest) Validate() error {
+	if !ValidPersonalMCPStdioAssetRef(r.AssetID, r.Version) {
+		return errors.New("invalid personal MCP asset reference")
+	}
+	return (Request{SchemaVersion: RequestVersion, Action: "inspect", Lease: r.Lease}).Validate()
+}
+
+func ValidPersonalMCPStdioAssetRef(id, version string) bool {
+	return personalMCPAssetID.MatchString(id) && personalMCPVersion.MatchString(version)
+}

package/agent/guest/runtime.go

@@ -14,7 +14,7 @@ import (
 	"time"
 	"unicode/utf8"
 
-	env "github.com/opensoha/soha-contracts/agent/environment"
+	env "github.com/opensoha/soha/contracts/agent/environment"
 )
 
 const RuntimeOperationVersion = "opensoha.dev/personal-guest-runtime/v1"

package/agent/guest/runtime_test.go

@@ -7,7 +7,7 @@ import (
 	"testing"
 	"time"
 
-	env "github.com/opensoha/soha-contracts/agent/environment"
+	env "github.com/opensoha/soha/contracts/agent/environment"
 )
 
 func runtimeFixture(t *testing.T) (RuntimeOperation, time.Time) {

package/auth/catalog_generated.go

@@ -6,8 +6,8 @@ import _ "embed"
 
 const (
 	PermissionCatalogVersion = "2.0.0"
-	PermissionCatalogContentSHA256 = "bd4a7240d34750d3fcf38b4649f6dbe67b17fb0f6ebeb96a32f8d874685e5150"
-	PermissionCatalogSHA256 = "835ccdfccfa955ae3ee9377fffb4c523b53d2eb647d01840f79cce5524d72c36"
+	PermissionCatalogContentSHA256 = "132db706644d454f3706998f29f1ca9d7de4fece9a7adaeb00acc6597386104a"
+	PermissionCatalogSHA256 = "b1e46497db536a6aca9b909215ba8911ea4a3ed3885f604f238ffc43f3759a8f"
 )
 
 //go:embed permission-catalog.json

package/auth/docker_permissions_test.go

@@ -0,0 +1,44 @@
+package auth
+
+import (
+	"encoding/json"
+	"slices"
+	"testing"
+)
+
+func TestDockerRuntimeFilePermissionIsIndependent(t *testing.T) {
+	var catalog struct {
+		Permissions []struct {
+			Key            string   `json:"key"`
+			Resource       string   `json:"resource"`
+			Action         string   `json:"action"`
+			RiskLevel      string   `json:"riskLevel"`
+			ScopeKinds     []string `json:"scopeKinds"`
+			ApprovalPolicy string   `json:"approvalPolicy"`
+			Status         string   `json:"status"`
+			Assignable     bool     `json:"assignable"`
+			LegacyAliases  []string `json:"legacyAliases"`
+			ReplacedBy     []string `json:"replacedBy"`
+		} `json:"permissions"`
+	}
+	if err := json.Unmarshal(PermissionCatalogJSON(), &catalog); err != nil {
+		t.Fatal(err)
+	}
+	found := 0
+	for _, p := range catalog.Permissions {
+		if p.Key == "docker.services.files" {
+			found++
+			if p.Resource != "services" || p.Action != "files" || p.RiskLevel != "high" || p.ApprovalPolicy != "eligible" || p.Status != "active" || !p.Assignable || len(p.LegacyAliases) != 0 || !slices.Equal(p.ScopeKinds, []string{"workspace", "project", "resource"}) {
+				t.Fatalf("file permission must be explicit and independent: %+v", p)
+			}
+		}
+		if p.Key == "docker.services.view" || p.Key == "docker.services.manage" || p.Key == "docker.services.actions" {
+			if slices.Contains(p.ReplacedBy, "docker.services.files") {
+				t.Fatalf("coarse key must not implicitly grant new file permission: %s", p.Key)
+			}
+		}
+	}
+	if found != 1 {
+		t.Fatalf("file permission count = %d, want exactly one", found)
+	}
+}

package/auth/permission-catalog.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "authorization.opensoha.io/v1",
   "catalogVersion": "2.0.0",
-  "contentHash": "sha256:bd4a7240d34750d3fcf38b4649f6dbe67b17fb0f6ebeb96a32f8d874685e5150",
+  "contentHash": "sha256:132db706644d454f3706998f29f1ca9d7de4fece9a7adaeb00acc6597386104a",
   "permissions": [
     {
       "key": "access.directory.create",
@@ -4138,6 +4138,22 @@
         "docker.services.terminal"
       ]
     },
+    {
+      "key": "docker.services.files",
+      "domain": "docker",
+      "resource": "services",
+      "action": "files",
+      "displayName": "读取 Docker 服务卷文件",
+      "riskLevel": "high",
+      "scopeKinds": [
+        "workspace",
+        "project",
+        "resource"
+      ],
+      "approvalPolicy": "eligible",
+      "status": "active",
+      "assignable": true
+    },
     {
       "key": "docker.services.logs",
       "domain": "docker",
@@ -5366,6 +5382,54 @@
       "status": "active",
       "assignable": true
     },
+    {
+      "key": "network_access.nas_bindings.create",
+      "domain": "network_access",
+      "resource": "nas_bindings",
+      "action": "create",
+      "displayName": "创建站点范围托管 NAS/RADIUS 服务",
+      "riskLevel": "mutate",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.nas_bindings.update",
+      "domain": "network_access",
+      "resource": "nas_bindings",
+      "action": "update",
+      "displayName": "修改站点范围托管 NAS/RADIUS 服务",
+      "riskLevel": "mutate",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.nas_bindings.view",
+      "domain": "network_access",
+      "resource": "nas_bindings",
+      "action": "view",
+      "displayName": "查看站点范围托管 NAS/RADIUS 服务",
+      "riskLevel": "read",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
     {
       "key": "network_access.policy.create",
       "domain": "network_access",

package/auth/radius_permissions_test.go

@@ -0,0 +1,44 @@
+package auth
+
+import (
+	"encoding/json"
+	"slices"
+	"testing"
+)
+
+func TestManagedNASRADIUSPermissionsAreAssignableAndScoped(t *testing.T) {
+	var c struct {
+		Permissions []struct {
+			Key, Domain, Resource, Action, RiskLevel, Status, DisplayName string
+			ScopeKinds                                                    []string
+			Assignable                                                    bool
+			LegacyAliases                                                 []string
+		}
+	}
+	if e := json.Unmarshal(PermissionCatalogJSON(), &c); e != nil {
+		t.Fatal(e)
+	}
+	found := map[string]bool{}
+	for _, p := range c.Permissions {
+		if p.Key == "network_access.nas_bindings.delete" {
+			t.Fatal("unapproved delete grant")
+		}
+		for _, action := range []string{"view", "create", "update"} {
+			key := "network_access.nas_bindings." + action
+			if p.Key != key {
+				continue
+			}
+			risk := "mutate"
+			if action == "view" {
+				risk = "read"
+			}
+			if p.Domain != "network_access" || p.Resource != "nas_bindings" || p.Action != action || p.Status != "active" || !p.Assignable || p.RiskLevel != risk || !slices.Contains(p.ScopeKinds, "resource") || len(p.LegacyAliases) != 0 {
+				t.Fatalf("invalid managed NAS permission: %+v", p)
+			}
+			found[key] = true
+		}
+	}
+	if len(found) != 3 {
+		t.Fatalf("managed NAS catalog missing keys: %v", found)
+	}
+}

package/compat/consumer-revisions.json

@@ -1,8 +1,8 @@
 {
-  "soha": "59e929046927eecf1977bc50a446fd5d823d1d31",
-  "soha-web": "447cbe5358802ef40d86ac67b7b59c5afe9c846a",
-  "soha-app": "0c3c76c373246f7d2218b48f68b89bf3097f777b",
-  "soha-cli": "1c9b760c986a9c1a5148db55b72ab99d23edd7a3",
-  "soha-agent": "af1efc0b0cd6bb544153429fa28244dd6cc81ac7",
-  "soha-skills": "bc115fab583d00d4cc7350d8f314077d11bb5488"
+  "soha": "a0885220969bc6a37ac75672214e6fe0b6d2926a",
+  "soha-web": "83bcb548005e34ecf86bfc5b56804e680b0d5898",
+  "soha-app": "e51ef3fc0e46d89d62da79bf4cc1813ff797049b",
+  "soha-cli": "71301b9fb9f9f2b4acd500483c08094a1b9be83a",
+  "soha-agent": "d8ce67c5b52b9b314e8fd6c1f42af9a0313e6db2",
+  "soha-skills": "e562189e1416a9e2f8c72f9018e2236dc8d23dd1"
 }

package/compat/openapi-loose-boundaries-0.1.0.json

@@ -298,6 +298,10 @@
       "kind": "additionalPropertiesTrue",
       "path": "components/schemas/ExecutionCallbackRequest/properties/payload/additionalProperties"
     },
+    {
+      "kind": "additionalPropertiesTrue",
+      "path": "components/schemas/ExecutionLog/properties/metadata/additionalProperties"
+    },
     {
       "kind": "additionalPropertiesTrue",
       "path": "components/schemas/ExecutionTask/additionalProperties"

package/docker/runtime/compose.go

@@ -0,0 +1,128 @@
+package runtime
+
+import (
+	"encoding/json"
+	"errors"
+	"strings"
+
+	"sigs.k8s.io/yaml"
+)
+
+// BindCompose returns an execution copy. The user's stored document is retained.
+// Explicit container_name is incompatible with isolated project namespaces.
+func BindCompose(content string, binding ProjectBinding) (string, error) {
+	if err := binding.Validate(); err != nil {
+		return "", err
+	}
+	if len(content) == 0 || len(content) > 2<<20 {
+		return "", errors.New("docker Compose document exceeds the runtime boundary")
+	}
+	raw, err := yaml.YAMLToJSONStrict([]byte(content))
+	if err != nil {
+		return "", errors.New("docker Compose document is invalid")
+	}
+	var document map[string]any
+	if json.Unmarshal(raw, &document) != nil {
+		return "", errors.New("docker Compose document must be an object")
+	}
+	services, ok := document["services"].(map[string]any)
+	if !ok || len(services) == 0 || len(services) > 256 {
+		return "", errors.New("docker Compose services are invalid")
+	}
+	if _, exists := document["include"]; exists {
+		return "", errors.New("compose include is unsupported for identity-bound projects")
+	}
+	for name, value := range services {
+		service, err := bindComposeService(name, value, binding)
+		if err != nil {
+			return "", err
+		}
+		services[name] = service
+	}
+	document["name"] = binding.Namespace
+	encoded, err := yaml.Marshal(document)
+	return string(encoded), err
+}
+
+func bindComposeService(name string, value any, binding ProjectBinding) (map[string]any, error) {
+	service, ok := value.(map[string]any)
+	if !ok || !serviceNamePattern.MatchString(name) {
+		return nil, errors.New("docker Compose service is invalid")
+	}
+	for _, field := range []string{"container_name", "extends"} {
+		if _, exists := service[field]; exists {
+			return nil, errors.New("explicit container_name or extends is unsupported for identity-bound projects")
+		}
+	}
+	if err := validateSingleContainerService(service); err != nil {
+		return nil, err
+	}
+	labels, err := boundLabels(service["labels"], binding)
+	if err != nil {
+		return nil, err
+	}
+	service["labels"] = labels
+	return service, nil
+}
+
+// Identity v1 registers one immutable CID per service. Reject dynamic or
+// multi-replica input before Compose can create unregistered containers.
+func validateSingleContainerService(service map[string]any) error {
+	if value, present := service["scale"]; present && !singleReplica(value) {
+		return errors.New("identity-bound Compose requires exactly one container per service")
+	}
+	if value, present := service["deploy"]; present {
+		deploy, ok := value.(map[string]any)
+		if !ok {
+			return errors.New("identity-bound Compose deploy configuration is invalid")
+		}
+		if value, present := deploy["replicas"]; present && !singleReplica(value) {
+			return errors.New("identity-bound Compose requires exactly one container per service")
+		}
+		if value, present := deploy["mode"]; present && value != "replicated" {
+			return errors.New("identity-bound Compose requires replicated service mode")
+		}
+	}
+	return nil
+}
+
+func singleReplica(value any) bool { return value == float64(1) || value == "1" }
+
+func boundLabels(value any, binding ProjectBinding) (map[string]string, error) {
+	labels := map[string]string{}
+	switch input := value.(type) {
+	case nil:
+	case map[string]any:
+		for key, raw := range input {
+			text, ok := raw.(string)
+			if !ok {
+				return nil, errors.New("docker Compose labels must be strings")
+			}
+			labels[key] = text
+		}
+	case []any:
+		for _, raw := range input {
+			text, ok := raw.(string)
+			if !ok {
+				return nil, errors.New("docker Compose labels must be strings")
+			}
+			key, val, found := strings.Cut(text, "=")
+			if !found || key == "" {
+				return nil, errors.New("docker Compose labels require explicit values")
+			}
+			if _, duplicate := labels[key]; duplicate {
+				return nil, errors.New("docker Compose label is duplicated")
+			}
+			labels[key] = val
+		}
+	default:
+		return nil, errors.New("docker Compose labels are invalid")
+	}
+	for key, val := range binding.Labels() {
+		if previous, exists := labels[key]; exists && previous != val {
+			return nil, errors.New("docker runtime identity label is reserved")
+		}
+		labels[key] = val
+	}
+	return labels, nil
+}

package/docker/runtime/compose_replicas_test.go

@@ -0,0 +1,20 @@
+package runtime
+
+import "testing"
+
+func TestBoundComposeRejectsUnregisteredReplicaShapesBeforeExecution(t *testing.T) {
+	binding, _ := NewProjectBinding("11111111-1111-4111-8111-111111111111", "22222222-2222-4222-8222-222222222222")
+	for _, extra := range []string{"", "    scale: 1\n", "    scale: '1'\n", "    deploy:\n      replicas: 1\n      mode: replicated\n"} {
+		if _, err := BindCompose("services:\n  web:\n    image: fixture\n"+extra, binding); err != nil {
+			t.Fatal(extra, err)
+		}
+	}
+	for _, extra := range []string{
+		"    scale: 2\n", "    scale: 0\n", "    scale: '${REPLICAS}'\n", "    scale: [1]\n", "    scale: {}\n",
+		"    deploy:\n      replicas: 2\n", "    deploy:\n      replicas: '${REPLICAS}'\n", "    deploy:\n      mode: global\n", "    deploy: []\n",
+	} {
+		if _, err := BindCompose("services:\n  web:\n    image: fixture\n"+extra, binding); err == nil {
+			t.Fatal("unregistered replica shape accepted", extra)
+		}
+	}
+}

package/docker/runtime/container_set.go

@@ -0,0 +1,50 @@
+package runtime
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+)
+
+// ContainerSetFromValue decodes the complete set frozen before dispatch.
+// Empty must be explicit; null/missing is not a safe inventory snapshot.
+func ContainerSetFromValue(value any, project ProjectBinding) ([]ContainerBinding, error) {
+	raw, err := json.Marshal(value)
+	if err != nil || len(raw) > 256<<10 {
+		return nil, errors.New("docker original container set is invalid")
+	}
+	var containers []ContainerBinding
+	decoder := json.NewDecoder(bytes.NewReader(raw))
+	decoder.DisallowUnknownFields()
+	if decoder.Decode(&containers) != nil || containers == nil || len(containers) > 256 || project.Validate() != nil {
+		return nil, errors.New("docker original container set is missing or exceeds its limit")
+	}
+	names, ids := map[string]bool{}, map[string]bool{}
+	for _, item := range containers {
+		if item.Validate() != nil || item.ProjectBinding != project || names[item.ServiceName] || ids[item.ContainerID] {
+			return nil, errors.New("docker original container set is ambiguous")
+		}
+		names[item.ServiceName], ids[item.ContainerID] = true, true
+	}
+	return containers, nil
+}
+
+func SameContainerSet(expected, actual []ContainerBinding) bool {
+	if len(expected) != len(actual) {
+		return false
+	}
+	items := make(map[string]ContainerBinding, len(expected))
+	for _, item := range expected {
+		if _, duplicate := items[item.ContainerID]; duplicate {
+			return false
+		}
+		items[item.ContainerID] = item
+	}
+	for _, item := range actual {
+		if original, exists := items[item.ContainerID]; !exists || original != item {
+			return false
+		}
+		delete(items, item.ContainerID)
+	}
+	return len(items) == 0
+}

package/docker/runtime/container_set_test.go

@@ -0,0 +1,31 @@
+package runtime
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestOriginalContainerSetNeverAdoptsUnknownOrReplacement(t *testing.T) {
+	project, _ := NewProjectBinding("11111111-1111-4111-8111-111111111111", "22222222-2222-4222-8222-222222222222")
+	one := ContainerBinding{ProjectBinding: project, ServiceName: "one", ContainerID: strings.Repeat("a", 64)}
+	two := ContainerBinding{ProjectBinding: project, ServiceName: "two", ContainerID: strings.Repeat("b", 64)}
+	set, err := ContainerSetFromValue([]ContainerBinding{one, two}, project)
+	if err != nil || !SameContainerSet(set, []ContainerBinding{two, one}) {
+		t.Fatal("valid unordered container set rejected", err)
+	}
+	for _, raw := range []any{nil, "[]", []ContainerBinding{one, one}, []any{map[string]any{"containerId": one.ContainerID}}, make([]ContainerBinding, 257)} {
+		if _, err := ContainerSetFromValue(raw, project); err == nil {
+			t.Fatal("ambiguous original inventory accepted", raw)
+		}
+	}
+	if empty, err := ContainerSetFromValue([]ContainerBinding{}, project); err != nil || len(empty) != 0 {
+		t.Fatal(err)
+	}
+	foreign := two
+	foreign.ContainerID = strings.Repeat("c", 64)
+	for _, actual := range [][]ContainerBinding{{one}, {one, foreign}, {one, two, foreign}, {one, one}} {
+		if SameContainerSet(set, actual) {
+			t.Fatal("changed inventory accepted")
+		}
+	}
+}

package/docker/runtime/identity.go

@@ -0,0 +1,130 @@
+// Package runtime owns the versioned Docker execution identity protocol.
+package runtime
+
+import (
+	"bytes"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"regexp"
+	"slices"
+
+	"github.com/google/uuid"
+)
+
+const (
+	IdentityProtocol = "docker-project-identity-v1"
+	HostUIDLabel     = "io.opensoha.host-uid"
+	ProjectUIDLabel  = "io.opensoha.project-uid"
+	ProtocolLabel    = "io.opensoha.runtime-protocol"
+)
+
+// ProjectBinding is supplied by the control plane, never by Compose input.
+// Labels corroborate this trusted binding; labels alone do not authorize access.
+type ProjectBinding struct {
+	Protocol   string `json:"protocol"`
+	HostUID    string `json:"hostUid"`
+	ProjectUID string `json:"projectUid"`
+	Namespace  string `json:"namespace"`
+}
+
+type ContainerBinding struct {
+	ProjectBinding
+	ServiceName string `json:"serviceName"`
+	ContainerID string `json:"containerId"`
+}
+
+var containerIDPattern = regexp.MustCompile(`^[0-9a-f]{64}$`)
+var serviceNamePattern = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$`)
+var protocolNamePattern = regexp.MustCompile(`^[a-z0-9][a-z0-9-]{0,63}$`)
+
+func NewProjectBinding(hostUID, projectUID string) (ProjectBinding, error) {
+	b := ProjectBinding{Protocol: IdentityProtocol, HostUID: hostUID, ProjectUID: projectUID}
+	if !canonicalUID(hostUID) || !canonicalUID(projectUID) {
+		return ProjectBinding{}, errors.New("docker resource UID is invalid")
+	}
+	digest := sha256.Sum256([]byte(hostUID + ":" + projectUID))
+	b.Namespace = "soha-" + hex.EncodeToString(digest[:26])
+	return b, nil
+}
+
+func canonicalUID(value string) bool {
+	id, err := uuid.Parse(value)
+	return err == nil && id != uuid.Nil && id.String() == value
+}
+
+func (b ProjectBinding) Validate() error {
+	expected, err := NewProjectBinding(b.HostUID, b.ProjectUID)
+	if err != nil || b != expected {
+		return errors.New("docker project runtime binding is invalid")
+	}
+	return nil
+}
+
+func (b ContainerBinding) Validate() error {
+	if err := b.ProjectBinding.Validate(); err != nil {
+		return err
+	}
+	if !serviceNamePattern.MatchString(b.ServiceName) || !containerIDPattern.MatchString(b.ContainerID) {
+		return errors.New("docker container runtime binding is invalid")
+	}
+	return nil
+}
+
+func (b ProjectBinding) Labels() map[string]string {
+	return map[string]string{HostUIDLabel: b.HostUID, ProjectUIDLabel: b.ProjectUID, ProtocolLabel: b.Protocol}
+}
+
+func ProjectBindingFromValue(value any) (ProjectBinding, error) {
+	var binding ProjectBinding
+	if decodeBinding(value, &binding) != nil || binding.Validate() != nil {
+		return ProjectBinding{}, errors.New("docker runtime binding is invalid")
+	}
+	return binding, nil
+}
+
+func ContainerBindingFromValue(value any) (ContainerBinding, error) {
+	var binding ContainerBinding
+	if decodeBinding(value, &binding) != nil || binding.Validate() != nil {
+		return ContainerBinding{}, errors.New("docker container binding is invalid")
+	}
+	return binding, nil
+}
+
+func decodeBinding(value any, binding any) error {
+	raw, err := json.Marshal(value)
+	if err != nil || len(raw) > 2048 {
+		return errors.New("docker runtime binding is invalid")
+	}
+	decoder := json.NewDecoder(bytes.NewReader(raw))
+	decoder.DisallowUnknownFields()
+	return decoder.Decode(binding)
+}
+
+func ValidateRuntimeProtocols(protocols []string) error {
+	if len(protocols) > 4 {
+		return errors.New("too many Docker runtime protocols")
+	}
+	for index, value := range protocols {
+		if !protocolNamePattern.MatchString(value) || slices.Contains(protocols[:index], value) {
+			return errors.New("docker runtime protocols are invalid or duplicated")
+		}
+	}
+	return nil
+}
+
+// MatchesContainer requires the full immutable Engine ID and both Compose
+// coordinates in addition to the control-plane identity labels. Never select a
+// different container after this check fails.
+func (b ContainerBinding) MatchesContainer(id string, labels map[string]string) bool {
+	if b.Validate() != nil || id != b.ContainerID || labels["com.docker.compose.project"] != b.Namespace || labels["com.docker.compose.service"] != b.ServiceName {
+		return false
+	}
+	for key, value := range b.Labels() {
+		if labels[key] != value {
+			return false
+		}
+	}
+	return true
+}