@opensoha/contracts 0.1.23 → 0.1.24

package/agent/environment/protocol.go

@@ -0,0 +1,221 @@
+// Package environment carries the Core-to-Agent personal environment protocol.
+// JSON Schemas in agent/ own the wire shapes; Docker handles stay Agent-private.
+package environment
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"regexp"
+	"strings"
+	"time"
+	"unicode/utf8"
+)
+
+const RequestVersion = "opensoha.dev/personal-environment-request/v1"
+const ResultVersion = "opensoha.dev/personal-environment-result/v1"
+const LeaseVersion = "opensoha.dev/environment-lease/v1"
+const SnapshotVersion = "opensoha.dev/environment-snapshot/v1"
+
+type Quota struct {
+	DiskBytes     int64 `json:"diskBytes"`
+	MemoryBytes   int64 `json:"memoryBytes"`
+	CPUUnits      int64 `json:"cpuUnits"`
+	MaxProcesses  int   `json:"maxProcesses"`
+	NetworkEgress bool  `json:"networkEgress"`
+}
+
+type Lease struct {
+	SchemaVersion string     `json:"schemaVersion"`
+	ID            string     `json:"id"`
+	RunID         string     `json:"runId"`
+	OwnerID       string     `json:"ownerId"`
+	ScopeHash     string     `json:"scopeHash"`
+	Mode          string     `json:"mode"`
+	WorkspacePath string     `json:"workspacePath,omitempty"`
+	Quota         Quota      `json:"quota"`
+	IssuedAt      time.Time  `json:"issuedAt"`
+	ExpiresAt     time.Time  `json:"expiresAt"`
+	ReleasedAt    *time.Time `json:"releasedAt,omitempty"`
+}
+
+type Usage struct {
+	DiskBytes    int64 `json:"diskBytes"`
+	MemoryBytes  int64 `json:"memoryBytes"`
+	CPUTimeNanos int64 `json:"cpuTimeNanos"`
+	Processes    int   `json:"processes"`
+}
+
+type Snapshot struct {
+	SchemaVersion string    `json:"schemaVersion"`
+	LeaseID       string    `json:"leaseId"`
+	RunID         string    `json:"runId"`
+	State         string    `json:"state"`
+	ResourceUsage Usage     `json:"resourceUsage"`
+	ArtifactRefs  []string  `json:"artifactRefs,omitempty"`
+	ObservedAt    time.Time `json:"observedAt"`
+}
+
+// Request is sent only by the trusted Core connection. Owner, scope, quota and
+// the original lease timestamps are server-derived, never user-selected.
+// Execute is not retryable: a lost receipt must be treated as an unknown outcome.
+type Request struct {
+	SchemaVersion string   `json:"schemaVersion"`
+	Action        string   `json:"action"`
+	Lease         Lease    `json:"lease"`
+	Argv          []string `json:"argv,omitempty"`
+	// TaskID selects a server-owned temporary directory inside the sandbox.
+	// It never changes the personal owner, lease or persistent mount.
+	TaskID string `json:"taskId,omitempty"`
+	// Core permits this only before the first successful provisioning receipt.
+	CreateData bool `json:"createData,omitempty"`
+}
+
+type Result struct {
+	SchemaVersion string    `json:"schemaVersion"`
+	LeaseID       string    `json:"leaseId"`
+	RunID         string    `json:"runId"`
+	TaskID        string    `json:"taskId,omitempty"`
+	State         string    `json:"state"`
+	Snapshot      *Snapshot `json:"snapshot,omitempty"`
+	Output        *string   `json:"output,omitempty"`
+	ExitCode      *int      `json:"exitCode,omitempty"`
+	ObservedAt    time.Time `json:"observedAt"`
+}
+
+var scopePattern = regexp.MustCompile(`^sha256:[a-f0-9]{64}$`)
+var canonicalUUIDPattern = regexp.MustCompile(`^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$`)
+
+func (r *Request) UnmarshalJSON(data []byte) error {
+	if !utf8.Valid(data) {
+		return errors.New("environment request must be UTF-8")
+	}
+	type wireRequest Request
+	var decoded wireRequest
+	decoder := json.NewDecoder(bytes.NewReader(data))
+	decoder.DisallowUnknownFields()
+	if err := decoder.Decode(&decoded); err != nil {
+		return err
+	}
+	var properties map[string]json.RawMessage
+	if err := json.Unmarshal(data, &properties); err != nil {
+		return err
+	}
+	if _, present := properties["argv"]; present && decoded.Action != "execute" {
+		return errors.New("only execute accepts command arguments")
+	}
+	if _, present := properties["taskId"]; present && (decoded.Action != "execute" || !canonicalUUIDPattern.MatchString(decoded.TaskID)) {
+		return errors.New("only execute accepts a canonical server task identity")
+	}
+	*r = Request(decoded)
+	return r.Validate()
+}
+
+func (r Request) Validate() error {
+	l := r.Lease
+	if r.SchemaVersion != RequestVersion || l.SchemaVersion != LeaseVersion || !scopePattern.MatchString(l.ScopeHash) {
+		return errors.New("invalid environment protocol identity")
+	}
+	for _, id := range []string{l.ID, l.RunID, l.OwnerID} {
+		if strings.TrimSpace(id) == "" || utf8.RuneCountInString(id) > 128 || !utf8.ValidString(id) || strings.ContainsRune(id, '\x00') {
+			return errors.New("invalid environment lease identity")
+		}
+	}
+	if (l.Mode != "observe-only" && l.Mode != "restricted-write") || l.WorkspacePath != "" || l.ReleasedAt != nil || l.IssuedAt.IsZero() || !l.ExpiresAt.After(l.IssuedAt) || l.ExpiresAt.Sub(l.IssuedAt) > 24*time.Hour {
+		return errors.New("invalid original personal environment lease")
+	}
+	if err := l.Quota.ValidatePersonalDocker(); err != nil {
+		return err
+	}
+	return r.validateAction()
+}
+
+func (q Quota) ValidatePersonalDocker() error {
+	if q.DiskBytes < 16<<20 || q.DiskBytes > 1<<40 || q.MemoryBytes < 32<<20 || q.MemoryBytes > 16<<30 || q.CPUUnits < 1 || q.CPUUnits > 8000 || q.MaxProcesses < 4 || q.MaxProcesses > 256 || q.NetworkEgress {
+		return errors.New("unsupported personal environment quota")
+	}
+	return nil
+}
+
+func (r Request) validateAction() error {
+	if r.TaskID != "" && (r.Action != "execute" || !canonicalUUIDPattern.MatchString(r.TaskID)) {
+		return errors.New("invalid personal execution task identity")
+	}
+	if r.CreateData && r.Action != "acquire" {
+		return errors.New("only initial acquisition can create persistent data")
+	}
+	if r.Action != "execute" {
+		if (r.Action != "acquire" && r.Action != "inspect" && r.Action != "release" && r.Action != "delete_data" && r.Action != "export_data") || r.Argv != nil {
+			return errors.New("invalid environment action")
+		}
+		return nil
+	}
+	if len(r.Argv) == 0 || len(r.Argv) > 64 || !strings.HasPrefix(r.Argv[0], "/") {
+		return errors.New("bounded absolute sandbox command required")
+	}
+	for _, arg := range r.Argv {
+		if len(arg) > 4096 || !utf8.ValidString(arg) || strings.ContainsRune(arg, '\x00') {
+			return errors.New("invalid sandbox command argument")
+		}
+	}
+	return nil
+}
+
+// ValidateFor binds a receipt to the dispatched operation. Stopped or missing
+// containers cannot claim fresh resource measurements or successful commands.
+func (result Result) ValidateFor(request Request) error {
+	if result.ExitCode != nil && (request.Action != "execute" || *result.ExitCode < 0 || *result.ExitCode > 255) {
+		return errors.New("invalid command exit receipt")
+	}
+	if request.Action == "export_data" {
+		return errors.New("export requires its complete binary stream receipt")
+	}
+	if result.SchemaVersion != ResultVersion || result.LeaseID != request.Lease.ID || result.RunID != request.Lease.RunID || result.TaskID != request.TaskID || result.ObservedAt.IsZero() {
+		return errors.New("environment receipt identity mismatch")
+	}
+	active := result.State == "active" || result.State == "quota_exceeded"
+	if !active && result.State != "released" && result.State != "expired" && result.State != "missing" && result.State != "deleted" {
+		return errors.New("invalid environment receipt state")
+	}
+	if request.Action == "release" && (result.State != "released" && result.State != "missing") {
+		return errors.New("release has no stopped receipt")
+	}
+	if request.Action == "delete_data" && result.State != "deleted" {
+		return errors.New("data deletion has no confirmed receipt")
+	}
+	if (request.Action == "acquire" || request.Action == "execute") && !active {
+		return errors.New("operation has no active receipt")
+	}
+	if !active {
+		if result.Snapshot != nil || result.Output != nil {
+			return errors.New("inactive receipt contains invented observation")
+		}
+		return nil
+	}
+	if err := result.validateObservation(); err != nil {
+		return err
+	}
+	if (request.Action == "execute") != (result.Output != nil) || (result.Output != nil && len(*result.Output) > 64<<10) {
+		return errors.New("invalid command receipt")
+	}
+	return nil
+}
+
+func (result Result) validateObservation() error {
+	s := result.Snapshot
+	if s == nil || s.SchemaVersion != SnapshotVersion || s.LeaseID != result.LeaseID || s.RunID != result.RunID || s.State != result.State || !s.ObservedAt.Equal(result.ObservedAt) {
+		return errors.New("environment observation identity mismatch")
+	}
+	u := s.ResourceUsage
+	if u.DiskBytes < 0 || u.MemoryBytes < 0 || u.CPUTimeNanos < 0 || u.Processes < 0 || len(s.ArtifactRefs) > 128 {
+		return errors.New("invalid environment observation")
+	}
+	seen := make(map[string]bool, len(s.ArtifactRefs))
+	for _, ref := range s.ArtifactRefs {
+		if utf8.RuneCountInString(ref) > 512 || seen[ref] {
+			return errors.New("invalid environment artifact reference")
+		}
+		seen[ref] = true
+	}
+	return nil
+}

package/agent/environment/protocol_test.go

@@ -0,0 +1,81 @@
+package environment
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+)
+
+func TestRequestFixturesMatchRuntimeBoundary(t *testing.T) {
+	for _, kind := range []string{"valid", "invalid"} {
+		files, err := filepath.Glob(filepath.Join("..", "..", "fixtures", "json-schema", "personal-environment-request", kind, "*.json"))
+		if err != nil || len(files) == 0 {
+			t.Fatalf("missing fixtures: %v", err)
+		}
+		for _, file := range files {
+			t.Run(kind+"/"+filepath.Base(file), func(t *testing.T) {
+				data, err := os.ReadFile(file)
+				if err != nil {
+					t.Fatal(err)
+				}
+				var request Request
+				err = json.Unmarshal(data, &request)
+				if (err == nil) != (kind == "valid") {
+					t.Fatalf("fixture acceptance=%t; want %s", err == nil, kind)
+				}
+			})
+		}
+	}
+}
+
+func TestRequestRejectsUnboundedOriginalLeaseAndNullCommand(t *testing.T) {
+	data, err := os.ReadFile(filepath.Join("..", "..", "fixtures", "json-schema", "personal-environment-request", "valid", "acquire.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	var request Request
+	if err := json.Unmarshal(data, &request); err != nil {
+		t.Fatal(err)
+	}
+	request.Lease.ExpiresAt = request.Lease.IssuedAt.Add(25 * time.Hour)
+	if request.Validate() == nil {
+		t.Fatal("unbounded lease accepted")
+	}
+	var properties map[string]any
+	if err := json.Unmarshal(data, &properties); err != nil {
+		t.Fatal(err)
+	}
+	properties["argv"] = nil
+	nullCommand, err := json.Marshal(properties)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if json.Unmarshal(nullCommand, &request) == nil {
+		t.Fatal("null command accepted by non-execute action")
+	}
+}
+
+func TestCommandReceiptPinsTheExactTemporaryTask(t *testing.T) {
+	now := time.Now().UTC()
+	request := Request{SchemaVersion: RequestVersion, Action: "execute", TaskID: "00000000-0000-4000-8000-000000000048", Argv: []string{"/bin/true"}, Lease: Lease{ID: "lease", RunID: "run"}}
+	text := "fixture"
+	result := Result{SchemaVersion: ResultVersion, LeaseID: "lease", RunID: "run", State: "active", Output: &text, ObservedAt: now, Snapshot: &Snapshot{SchemaVersion: SnapshotVersion, LeaseID: "lease", RunID: "run", State: "active", ObservedAt: now}}
+	for _, task := range []string{"", "00000000-0000-4000-8000-000000000049", request.TaskID} {
+		result.TaskID = task
+		if err := result.ValidateFor(request); (err == nil) != (task == request.TaskID) {
+			t.Fatal("command receipt changed or omitted its task identity")
+		}
+	}
+}
+
+func TestDataDeletionRequiresAConfirmedReceipt(t *testing.T) {
+	request := Request{Action: "delete_data", Lease: Lease{ID: "lease", RunID: "run"}}
+	for _, state := range []string{"missing", "released", "active", "deleted"} {
+		result := Result{SchemaVersion: ResultVersion, LeaseID: "lease", RunID: "run", State: state, ObservedAt: time.Now().UTC()}
+		if err := result.ValidateFor(request); (err == nil) != (state == "deleted") {
+			t.Fatalf("unconfirmed %s data deletion: %v", state, err)
+		}
+	}
+}

package/agent/environment-lease.schema.json

@@ -17,9 +17,9 @@
       "type": "object", "additionalProperties": false,
       "required": ["diskBytes", "memoryBytes", "cpuUnits", "maxProcesses", "networkEgress"],
       "properties": {
-        "diskBytes": { "type": "integer", "minimum": 1 },
+        "diskBytes": { "type": "integer", "minimum": 1, "description": "Maximum charged persistent storage bytes. The Docker personal backend uses a verified Btrfs subvolume quota; temporary task files use separately bounded memory-backed mounts and count against memoryBytes. Unsupported hard enforcement must fail acquisition." },
         "memoryBytes": { "type": "integer", "minimum": 1 },
-        "cpuUnits": { "type": "integer", "minimum": 1 },
+        "cpuUnits": { "type": "integer", "minimum": 1, "description": "CPU millicores: 1000 is one CPU. Docker personal leases must hard-enforce this ceiling." },
         "maxProcesses": { "type": "integer", "minimum": 1 },
         "networkEgress": { "type": "boolean" }
       }

package/agent/environment-template.schema.json

@@ -11,7 +11,7 @@
     "version": { "type": "string", "minLength": 1 },
     "backend": { "enum": ["local-process", "container", "kubernetes"] },
     "isolationMode": { "enum": ["observe-only", "restricted-write", "disposable-write"] },
-    "quota": { "type": "object", "required": ["cpuUnits", "memoryBytes", "diskBytes", "maxProcesses"], "properties": { "cpuUnits": { "type": "integer", "minimum": 1 }, "memoryBytes": { "type": "integer", "minimum": 1 }, "diskBytes": { "type": "integer", "minimum": 1 }, "maxProcesses": { "type": "integer", "minimum": 1 } }, "additionalProperties": false },
+    "quota": { "type": "object", "required": ["cpuUnits", "memoryBytes", "diskBytes", "maxProcesses"], "properties": { "cpuUnits": { "type": "integer", "minimum": 1, "description": "CPU millicores; 1000 is one CPU." }, "memoryBytes": { "type": "integer", "minimum": 1 }, "diskBytes": { "type": "integer", "minimum": 1, "description": "Maximum charged persistent storage bytes; memory-backed temporary mounts count against memoryBytes." }, "maxProcesses": { "type": "integer", "minimum": 1 } }, "additionalProperties": false },
     "networkEgress": { "type": "boolean" },
     "ttlSeconds": { "type": "integer", "minimum": 1, "maximum": 86400 },
     "enabled": { "type": "boolean" }

package/agent/guest/browser_network.go

@@ -0,0 +1,77 @@
+package guest
+
+import (
+	"encoding/base64"
+	"errors"
+	"net/url"
+	"strings"
+)
+
+// Only the private browser controller sends these frames over current mTLS.
+type BrowserNetworkRequest struct {
+	URL        string            `json:"url"`
+	Method     string            `json:"method"`
+	Headers    map[string]string `json:"headers,omitempty"`
+	BodyBase64 string            `json:"bodyBase64,omitempty"`
+}
+type BrowserNetworkHeader struct {
+	Name  string `json:"name"`
+	Value string `json:"value"`
+}
+type BrowserNetworkResponse struct {
+	Status     int                    `json:"status"`
+	Headers    []BrowserNetworkHeader `json:"headers"`
+	BodyBase64 string                 `json:"bodyBase64"`
+}
+
+func (v BrowserNetworkResponse) Validate() error {
+	if v.Status < 100 || v.Status > 599 || len(v.Headers) > 128 {
+		return errors.New("invalid browser network receipt")
+	}
+	data, err := base64.StdEncoding.DecodeString(v.BodyBase64)
+	if err != nil || len(data) > 1<<20 {
+		return errors.New("browser response exceeds its bound")
+	}
+	for _, h := range v.Headers {
+		if h.Name == "" || len(h.Name) > 128 || len(h.Value) > 8192 || strings.ContainsAny(h.Name+h.Value, "\x00\r\n") {
+			return errors.New("invalid browser response header")
+		}
+	}
+	return nil
+}
+
+func (v BrowserNetworkRequest) Validate() error {
+	u, err := url.Parse(v.URL)
+	if err != nil || !BrowserURL(v.URL) || u.Scheme != "https" || u.Fragment != "" || u.Opaque != "" || len(v.Headers) > 64 {
+		return errors.New("invalid browser network request")
+	}
+	switch v.Method {
+	case "GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS":
+	default:
+		return errors.New("unsupported browser network method")
+	}
+	body, err := base64.StdEncoding.DecodeString(v.BodyBase64)
+	if err != nil || len(body) > 64<<10 || (v.Method == "GET" || v.Method == "HEAD") && len(body) > 0 {
+		return errors.New("browser network body exceeds its bound")
+	}
+	size := 0
+	for name, value := range v.Headers {
+		size += len(name) + len(value)
+		if name == "" || strings.ContainsAny(name+value, "\x00\r\n") || len(name) > 128 || len(value) > 8192 {
+			return errors.New("invalid browser network header")
+		}
+	}
+	if size > 16<<10 {
+		return errors.New("browser network headers exceed their bound")
+	}
+	return nil
+}
+func (v *BrowserNetworkRequest) UnmarshalJSON(raw []byte) error {
+	type wire BrowserNetworkRequest
+	var decoded wire
+	if err := decodeStrictBounded(raw, &decoded, 128<<10, "url", "method", "headers", "bodyBase64"); err != nil {
+		return err
+	}
+	*v = BrowserNetworkRequest(decoded)
+	return v.Validate()
+}

package/agent/guest/data.go

@@ -0,0 +1,62 @@
+package guest
+
+import (
+	"errors"
+	"net/url"
+	"regexp"
+	"strings"
+	"time"
+)
+
+const DataPlanVersion = "opensoha.dev/personal-guest-data-plan/v1"
+
+// Core reserves operationId before fixed privileged dispatch. Liveness alone
+// cannot authorize this plan; GET /bindings/{id}/data-operations/{operationId}
+// returns it only for that current, running owner-authorized operation.
+type DataPlan struct {
+	SchemaVersion  string  `json:"schemaVersion"`
+	OperationID    string  `json:"operationId"`
+	Binding        Binding `json:"binding"`
+	DiskQuotaBytes int64   `json:"diskQuotaBytes"`
+}
+
+func (p DataPlan) Validate(now time.Time) error {
+	if p.SchemaVersion != DataPlanVersion || !uuidPattern.MatchString(p.OperationID) || p.Binding.Validate() != nil || p.Binding.Provider != "pve" || now.Before(p.Binding.IssuedAt) || !now.Before(p.Binding.ExpiresAt) || p.DiskQuotaBytes < 16<<20 || p.DiskQuotaBytes%1024 != 0 || p.DiskQuotaBytes >= p.Binding.DataDiskBytes {
+		return errors.New("invalid or expired personal data operation")
+	}
+	return nil
+}
+
+type DataResult struct {
+	DataRef      string `json:"dataRef"`
+	FilesystemID string `json:"filesystemId"`
+	DiskQuota    int64  `json:"diskQuotaBytes"`
+	DiskUsed     int64  `json:"diskUsedBytes"`
+	Reconciled   bool   `json:"reconciled"`
+}
+
+// Provisioning contains public identity material and a bootstrap-only challenge.
+// It is encrypted in the durable task and supplied only to the fixed QGA installer.
+// The private key is generated in the VM and never transported through Core.
+type Provisioning struct {
+	Plan           DataPlan `json:"plan"`
+	Endpoint       string   `json:"endpoint"`
+	EnrollmentID   string   `json:"enrollmentId"`
+	Challenge      string   `json:"challenge"`
+	CertificatePEM string   `json:"certificatePEM"`
+	ClientCAPEM    string   `json:"clientCAPEM"`
+	ArtifactSHA256 string   `json:"artifactSHA256"`
+	CPUQuotaMilli  int64    `json:"cpuQuotaMilli"`
+	MemoryBytes    int64    `json:"memoryBytes"`
+	PidsLimit      int64    `json:"pidsLimit"`
+	Network        bool     `json:"network"`
+}
+
+func (p Provisioning) Validate(now time.Time) error {
+	u, err := url.Parse(p.Endpoint)
+	_, tokenErr := EnrollmentTokenHash("Bearer " + p.Challenge)
+	if p.Plan.Validate(now) != nil || err != nil || u.Scheme != "https" || u.Host == "" || u.Path != "" || u.User != nil || u.RawQuery != "" || u.Fragment != "" || len(p.Endpoint) > 512 || strings.TrimSpace(p.Endpoint) != p.Endpoint || tokenErr != nil || (Enrollment{SchemaVersion: EnrollmentVersion, EnrollmentID: p.EnrollmentID}).Validate() != nil || !regexp.MustCompile(`^[a-f0-9]{64}$`).MatchString(p.ArtifactSHA256) || len(p.CertificatePEM) < 1 || len(p.CertificatePEM) > 4096 || len(p.ClientCAPEM) < 1 || len(p.ClientCAPEM) > 8192 || p.CPUQuotaMilli < 1 || p.CPUQuotaMilli > 8000 || p.MemoryBytes < 32<<20 || p.MemoryBytes > 16<<30 || p.PidsLimit < 4 || p.PidsLimit > 256 || p.Network {
+		return errors.New("invalid personal guest provisioning bundle")
+	}
+	return nil
+}