@opensoha/contracts 0.1.29 → 0.2.0

package/docker/runtime/identity_test.go

@@ -0,0 +1,91 @@
+package runtime
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestProjectIdentityNamespaceAndContainerFence(t *testing.T) {
+	a, err := NewProjectBinding("11111111-1111-4111-8111-111111111111", "22222222-2222-4222-8222-222222222222")
+	if err != nil || a.Validate() != nil {
+		t.Fatal(a, err)
+	}
+	b, _ := NewProjectBinding(a.HostUID, "33333333-3333-4333-8333-333333333333")
+	if a.Namespace == b.Namespace {
+		t.Fatal("recreated project reused namespace")
+	}
+	changedHost, _ := NewProjectBinding(b.ProjectUID, a.ProjectUID)
+	if a.Namespace == changedHost.Namespace {
+		t.Fatal("host identity ignored")
+	}
+	container := ContainerBinding{ProjectBinding: a, ServiceName: "web", ContainerID: strings.Repeat("a", 64)}
+	labels := a.Labels()
+	labels["com.docker.compose.project"] = a.Namespace
+	labels["com.docker.compose.service"] = "web"
+	if !container.MatchesContainer(container.ContainerID, labels) {
+		t.Fatal("matching container rejected")
+	}
+	for _, key := range []string{HostUIDLabel, ProjectUIDLabel, ProtocolLabel, "com.docker.compose.project", "com.docker.compose.service"} {
+		old := labels[key]
+		labels[key] = "other"
+		if container.MatchesContainer(container.ContainerID, labels) {
+			t.Fatal("identity mismatch accepted", key)
+		}
+		labels[key] = old
+	}
+	if container.MatchesContainer(strings.Repeat("b", 64), labels) {
+		t.Fatal("replacement container accepted")
+	}
+	for _, uid := range []string{"", a.HostUID + " ", strings.ToUpper(a.HostUID), "00000000-0000-0000-0000-000000000000"} {
+		if uid == a.HostUID {
+			continue
+		}
+		if _, err := NewProjectBinding(uid, a.ProjectUID); err == nil {
+			t.Fatal("invalid UID accepted", uid)
+		}
+	}
+}
+
+func TestBindComposePreservesInputAndRejectsAmbiguity(t *testing.T) {
+	b, _ := NewProjectBinding("11111111-1111-4111-8111-111111111111", "22222222-2222-4222-8222-222222222222")
+	for _, labels := range []string{"", "    labels: {purpose: task115}\n", "    labels: [purpose=task115]\n"} {
+		input := "name: user-name\nservices:\n  web:\n    image: alpine:3.21\n" + labels
+		out, err := BindCompose(input, b)
+		if err != nil || !strings.Contains(out, b.Namespace) || !strings.Contains(out, b.ProjectUID) || !strings.Contains(input, "name: user-name") {
+			t.Fatal(out, err)
+		}
+		again, err := BindCompose(out, b)
+		if err != nil || again != out {
+			t.Fatal("execution binding is not idempotent", err)
+		}
+	}
+	for _, input := range []string{"null", "[]", "services: {}", "services:\n  web:\n    image: one\n    image: two", "services:\n  web:\n    container_name: other", "services:\n  web:\n    labels:\n      io.opensoha.project-uid: other", "services:\n  web:\n    labels: [x=1, x=2]", "services:\n  web:\n    extends: base\n  base:\n    container_name: other", "include: outside.yaml\nservices:\n  web:\n    image: alpine"} {
+		if _, err := BindCompose(input, b); err == nil {
+			t.Fatal("unsafe Compose accepted", input)
+		}
+	}
+}
+
+func TestRuntimeClaimProtocolsAndStrictContainerDecode(t *testing.T) {
+	for _, values := range [][]string{nil, {IdentityProtocol}, {"future-protocol"}} {
+		if err := ValidateRuntimeProtocols(values); err != nil {
+			t.Fatal(values, err)
+		}
+	}
+	for _, values := range [][]string{{IdentityProtocol, IdentityProtocol}, {""}, {"UPPER"}, {"space value"}, {strings.Repeat("a", 65)}, {"a", "b", "c", "d", "e"}} {
+		if ValidateRuntimeProtocols(values) == nil {
+			t.Fatal("invalid protocols accepted", values)
+		}
+	}
+	p, _ := NewProjectBinding("11111111-1111-4111-8111-111111111111", "22222222-2222-4222-8222-222222222222")
+	b := ContainerBinding{ProjectBinding: p, ServiceName: "web", ContainerID: strings.Repeat("a", 64)}
+	if decoded, err := ContainerBindingFromValue(b); err != nil || decoded != b {
+		t.Fatal(decoded, err)
+	}
+	if _, err := ContainerBindingFromValue(p); err == nil {
+		t.Fatal("project-only target accepted as container")
+	}
+	if _, err := ProjectBindingFromValue(b); err == nil {
+		t.Fatal("extra container fields accepted as project binding")
+	}
+}

package/docker/runtime/read.go

@@ -0,0 +1,141 @@
+package runtime
+
+import (
+	"errors"
+	"path"
+	"strings"
+	"unicode"
+	"unicode/utf8"
+)
+
+const ReadProtocol = "docker-runtime-read-v1"
+
+// ReadRequest never carries Compose, environment, bearer credentials or a host
+// source path. The container binding comes from the control plane registry.
+type ReadRequest struct {
+	Protocol     string           `json:"protocol"`
+	Action       string           `json:"action"`
+	ProjectID    string           `json:"projectId"`
+	Container    ContainerBinding `json:"container"`
+	TailLines    int              `json:"tailLines,omitempty"`
+	SinceSeconds int64            `json:"sinceSeconds,omitempty"`
+	Target       string           `json:"target,omitempty"`
+	Path         string           `json:"path,omitempty"`
+	Limit        int              `json:"limit,omitempty"`
+	LimitBytes   int64            `json:"limitBytes,omitempty"`
+}
+
+type Volume struct {
+	Target            string `json:"target"`
+	Type              string `json:"type"`
+	ReadOnly          bool   `json:"readOnly"`
+	BrowseSupported   bool   `json:"browseSupported"`
+	UnsupportedReason string `json:"unsupportedReason,omitempty"`
+}
+
+type FileEntry struct {
+	Name          string `json:"name"`
+	Path          string `json:"path"`
+	Kind          string `json:"kind"`
+	SizeBytes     int64  `json:"sizeBytes"`
+	ModifiedAt    string `json:"modifiedAt,omitempty"`
+	ReadSupported bool   `json:"readSupported"`
+	ListSupported bool   `json:"listSupported"`
+}
+
+type ReadResult struct {
+	Protocol  string           `json:"protocol"`
+	Action    string           `json:"action"`
+	ProjectID string           `json:"projectId"`
+	Container ContainerBinding `json:"container"`
+	Target    string           `json:"target,omitempty"`
+	Path      string           `json:"path,omitempty"`
+	Content   string           `json:"content,omitempty"`
+	Encoding  string           `json:"encoding,omitempty"`
+	SizeBytes int64            `json:"sizeBytes"`
+	// ReturnedBytes is the UTF-8 payload length. For files.read, SizeBytes is
+	// the source file's full size and can be larger when Truncated is true.
+	ReturnedBytes int64       `json:"returnedBytes"`
+	Truncated     bool        `json:"truncated"`
+	Complete      bool        `json:"complete"`
+	Volumes       []Volume    `json:"volumes"`
+	Files         []FileEntry `json:"files"`
+}
+
+func (r ReadRequest) Normalized(action string) (ReadRequest, error) {
+	if r.Protocol != ReadProtocol || r.Action != action || !SafeText(r.ProjectID, 128) || strings.TrimSpace(r.ProjectID) != r.ProjectID || r.ProjectID == "" || r.Container.Validate() != nil {
+		return ReadRequest{}, errors.New("docker versioned read identity is invalid")
+	}
+	switch action {
+	case "logs":
+		return r.normalizedLogs()
+	case "volumes":
+		if r.Target != "" || r.Path != "" || r.Limit != 0 || r.LimitBytes != 0 || r.TailLines != 0 || r.SinceSeconds != 0 {
+			return ReadRequest{}, errors.New("docker volume inventory does not accept file or log options")
+		}
+	case "files.list", "files.read":
+		return r.normalizedFiles(action)
+	default:
+		return ReadRequest{}, errors.New("docker versioned read action is unsupported")
+	}
+	return r, nil
+}
+
+func (r ReadRequest) normalizedLogs() (ReadRequest, error) {
+	if r.Target != "" || r.Path != "" || r.Limit != 0 || r.TailLines < 0 || r.TailLines > 2000 || r.SinceSeconds < 0 || r.SinceSeconds > 604800 || r.LimitBytes < 0 || r.LimitBytes > 1<<20 {
+		return ReadRequest{}, errors.New("docker log read options are invalid")
+	}
+	if r.TailLines == 0 {
+		r.TailLines = 200
+	}
+	if r.LimitBytes == 0 {
+		r.LimitBytes = 1 << 20
+	}
+	return r, nil
+}
+
+func (r ReadRequest) normalizedFiles(action string) (ReadRequest, error) {
+	if !ValidMountTarget(r.Target) || !ValidRelativePath(r.Path) || r.TailLines != 0 || r.SinceSeconds != 0 {
+		return ReadRequest{}, errors.New("docker volume file target or path is invalid")
+	}
+	if action == "files.list" {
+		if r.Limit < 0 || r.Limit > 1000 || r.LimitBytes != 0 {
+			return ReadRequest{}, errors.New("docker directory read limit is invalid")
+		}
+		if r.Limit == 0 {
+			r.Limit = 200
+		}
+	} else {
+		if r.Limit != 0 || r.LimitBytes < 0 || r.LimitBytes > 1<<20 {
+			return ReadRequest{}, errors.New("docker file read limit is invalid")
+		}
+		if r.LimitBytes == 0 {
+			r.LimitBytes = 256 << 10
+		}
+	}
+	if r.Path == "." {
+		r.Path = ""
+	}
+	return r, nil
+}
+
+func SafeText(value string, maximum int) bool {
+	if len(value) > maximum || !utf8.ValidString(value) {
+		return false
+	}
+	return !strings.ContainsFunc(value, unicode.IsControl)
+}
+
+func ValidMountTarget(value string) bool {
+	return SafeText(value, 4096) && strings.HasPrefix(value, "/") && value != "/" && path.Clean(value) == value && !strings.Contains(value, `\`)
+}
+
+func ValidRelativePath(value string) bool {
+	if !SafeText(value, 4096) || strings.Contains(value, `\`) || strings.HasPrefix(value, "/") {
+		return false
+	}
+	if value == "" || value == "." {
+		return true
+	}
+	return path.Clean(value) == value && value != ".." && !strings.HasPrefix(value, "../")
+}

package/docker/runtime/read_result.go

@@ -0,0 +1,93 @@
+package runtime
+
+import (
+	"errors"
+	"path"
+	"strings"
+	"unicode/utf8"
+)
+
+// ValidateFor binds an untrusted runtime response to the original normalized
+// request. Callers must not accept a successful HTTP status as identity proof.
+func (r ReadResult) ValidateFor(request ReadRequest) error {
+	req, err := request.Normalized(request.Action)
+	if err != nil || r.Protocol != ReadProtocol || r.Action != req.Action || r.ProjectID != req.ProjectID || r.Container != req.Container || r.Target != req.Target || r.Path != req.Path {
+		return errors.New("docker read response identity differs from the original request")
+	}
+	if r.Volumes == nil || r.Files == nil || r.SizeBytes < 0 || r.ReturnedBytes < 0 || r.Complete == r.Truncated {
+		return errors.New("docker read response completeness is invalid")
+	}
+	switch req.Action {
+	case "logs", "files.read":
+		return r.validateTextResult(req)
+	case "volumes":
+		return r.validateVolumes()
+	case "files.list":
+		return r.validateFiles(req)
+	}
+	return errors.New("docker read response action is unsupported")
+}
+
+func (r ReadResult) validateTextResult(req ReadRequest) error {
+	if r.Encoding != "utf-8" || !utf8.ValidString(r.Content) || strings.ContainsRune(r.Content, 0) || int64(len(r.Content)) > req.LimitBytes || r.ReturnedBytes != int64(len(r.Content)) || len(r.Files) != 0 || len(r.Volumes) != 0 {
+		return errors.New("docker read text response is invalid or exceeds its limit")
+	}
+	if req.Action == "logs" && r.SizeBytes != r.ReturnedBytes {
+		return errors.New("docker log response byte count is invalid")
+	}
+	if req.Action == "files.read" && (r.SizeBytes < r.ReturnedBytes || r.Truncated != (r.SizeBytes > r.ReturnedBytes)) {
+		return errors.New("docker file source size or truncation is invalid")
+	}
+	return nil
+}
+
+func (r ReadResult) validateVolumes() error {
+	if len(r.Volumes) > 256 || len(r.Files) != 0 || r.Content != "" || r.Encoding != "" || r.SizeBytes != 0 || r.ReturnedBytes != 0 || !r.Complete {
+		return errors.New("docker read volume response is invalid")
+	}
+	seen := map[string]bool{}
+	for _, volume := range r.Volumes {
+		if !ValidMountTarget(volume.Target) || seen[volume.Target] || !SafeText(volume.Type, 32) || volume.Type == "" || !SafeText(volume.UnsupportedReason, 256) || volume.BrowseSupported == (volume.UnsupportedReason != "") {
+			return errors.New("docker read volume metadata is invalid")
+		}
+		seen[volume.Target] = true
+	}
+	return nil
+}
+
+func (r ReadResult) validateFiles(req ReadRequest) error {
+	if len(r.Files) > req.Limit || len(r.Volumes) != 0 || r.Content != "" || r.Encoding != "" || r.SizeBytes != 0 || r.ReturnedBytes != 0 {
+		return errors.New("docker read directory response is invalid")
+	}
+	seen := map[string]bool{}
+	for _, file := range r.Files {
+		if err := file.validate(req.Path); err != nil || seen[file.Name] {
+			return errors.New("docker read file entry is invalid")
+		}
+		seen[file.Name] = true
+	}
+	return nil
+}
+
+func (f FileEntry) validate(parent string) error {
+	if f.Name == "" || f.Name == "." || f.Name == ".." || strings.Contains(f.Name, "/") || !ValidRelativePath(f.Name) || f.Path != path.Join(parent, f.Name) || f.SizeBytes < 0 || !SafeText(f.ModifiedAt, 64) {
+		return errors.New("docker file entry path or metadata is invalid")
+	}
+	switch f.Kind {
+	case "file":
+		if f.ListSupported {
+			return errors.New("docker file cannot be listed as a directory")
+		}
+	case "directory":
+		if f.ReadSupported {
+			return errors.New("docker directory cannot be read as a file")
+		}
+	case "symlink", "other":
+		if f.ReadSupported || f.ListSupported {
+			return errors.New("docker special file access is unsupported")
+		}
+	default:
+		return errors.New("docker file entry kind is unsupported")
+	}
+	return nil
+}

package/docker/runtime/read_result_test.go

@@ -0,0 +1,111 @@
+package runtime
+
+import (
+	"strings"
+	"testing"
+)
+
+func readFixture(action string) (ReadRequest, ReadResult) {
+	project, _ := NewProjectBinding("11111111-1111-4111-8111-111111111111", "22222222-2222-4222-8222-222222222222")
+	req := ReadRequest{Protocol: ReadProtocol, Action: action, ProjectID: "project", Container: ContainerBinding{ProjectBinding: project, ServiceName: "web", ContainerID: strings.Repeat("a", 64)}}
+	if strings.HasPrefix(action, "files.") {
+		req.Target = "/data"
+	}
+	req, _ = req.Normalized(action)
+	r := ReadResult{Protocol: ReadProtocol, Action: action, ProjectID: req.ProjectID, Container: req.Container, Target: req.Target, Complete: true, Volumes: []Volume{}, Files: []FileEntry{}}
+	if action == "logs" || action == "files.read" {
+		r.Encoding = "utf-8"
+	}
+	return req, r
+}
+
+func TestReadResultBindsExactRequestAndExplicitCompleteness(t *testing.T) {
+	for _, action := range []string{"logs", "volumes", "files.list", "files.read"} {
+		t.Run(action, func(t *testing.T) {
+			req, result := readFixture(action)
+			if err := result.ValidateFor(req); err != nil {
+				t.Fatal(err)
+			}
+			for name, change := range map[string]func(*ReadResult){
+				"replacement":                func(r *ReadResult) { r.Container.ContainerID = strings.Repeat("b", 64) },
+				"project":                    func(r *ReadResult) { r.ProjectID = "other" },
+				"protocol":                   func(r *ReadResult) { r.Protocol = "old" },
+				"target":                     func(r *ReadResult) { r.Target = "/other" },
+				"missing inventory":          func(r *ReadResult) { r.Volumes = nil },
+				"missing files":              func(r *ReadResult) { r.Files = nil },
+				"unknown completeness":       func(r *ReadResult) { r.Complete = false },
+				"contradictory completeness": func(r *ReadResult) { r.Truncated = true },
+			} {
+				t.Run(name, func(t *testing.T) {
+					r := result
+					change(&r)
+					if r.ValidateFor(req) == nil {
+						t.Fatal("invalid result accepted")
+					}
+				})
+			}
+		})
+	}
+}
+
+func TestReadResultRejectsEscapesSpecialFilesAndUnboundedText(t *testing.T) {
+	req, r := readFixture("files.list")
+	r.Files = []FileEntry{{Name: "文件.txt", Path: "文件.txt", Kind: "file", ReadSupported: true}}
+	if err := r.ValidateFor(req); err != nil {
+		t.Fatal(err)
+	}
+	for _, file := range []FileEntry{
+		{Name: "../outside", Path: "../outside", Kind: "file"},
+		{Name: "file", Path: "elsewhere/file", Kind: "file"},
+		{Name: "link", Path: "link", Kind: "symlink", ReadSupported: true},
+		{Name: "fifo", Path: "fifo", Kind: "other", ListSupported: true},
+		{Name: "dir", Path: "dir", Kind: "directory", ReadSupported: true},
+	} {
+		r.Files = []FileEntry{file}
+		if r.ValidateFor(req) == nil {
+			t.Fatal("unsafe entry accepted", file)
+		}
+	}
+	req, r = readFixture("logs")
+	for _, content := range []string{string([]byte{0xff}), "binary\x00", strings.Repeat("x", int(req.LimitBytes)+1)} {
+		r.Content, r.SizeBytes = content, int64(len(content))
+		if r.ValidateFor(req) == nil {
+			t.Fatal("unsafe or oversized text accepted")
+		}
+	}
+	req, r = readFixture("volumes")
+	r.Volumes = []Volume{{Target: "/data", Type: "bind", UnsupportedReason: "reader disabled"}}
+	if err := r.ValidateFor(req); err != nil {
+		t.Fatal(err)
+	}
+	r.Volumes = append(r.Volumes, r.Volumes[0])
+	if r.ValidateFor(req) == nil {
+		t.Fatal("duplicate mount accepted")
+	}
+}
+
+func TestFileReadReportsActualSourceSizeSeparatelyFromReturnedText(t *testing.T) {
+	req, r := readFixture("files.read")
+	r.Content, r.ReturnedBytes, r.SizeBytes = "中", 3, 20
+	r.Truncated, r.Complete = true, false
+	if err := r.ValidateFor(req); err != nil {
+		t.Fatal(err)
+	}
+	r.ReturnedBytes = 2
+	if r.ValidateFor(req) == nil {
+		t.Fatal("incorrect UTF-8 payload size accepted")
+	}
+	r.ReturnedBytes = 3
+	r.SizeBytes = 3
+	if r.ValidateFor(req) == nil {
+		t.Fatal("truncation without additional source bytes accepted")
+	}
+	r.Truncated, r.Complete = false, true
+	if err := r.ValidateFor(req); err != nil {
+		t.Fatal(err)
+	}
+	r.SizeBytes = 20
+	if r.ValidateFor(req) == nil {
+		t.Fatal("incomplete file claimed complete")
+	}
+}

package/docker/runtime/read_test.go

@@ -0,0 +1,63 @@
+package runtime
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestReadRequestRequiresFullIdentityAndActionSpecificBounds(t *testing.T) {
+	project, _ := NewProjectBinding("11111111-1111-4111-8111-111111111111", "22222222-2222-4222-8222-222222222222")
+	base := ReadRequest{Protocol: ReadProtocol, ProjectID: "project", Container: ContainerBinding{ProjectBinding: project, ServiceName: "web", ContainerID: strings.Repeat("a", 64)}}
+	for _, action := range []string{"logs", "volumes", "files.list", "files.read"} {
+		t.Run(action, func(t *testing.T) {
+			r := base
+			r.Action = action
+			if strings.HasPrefix(action, "files.") {
+				r.Target, r.Path = "/data", "."
+			}
+			if _, err := r.Normalized(action); err != nil {
+				t.Fatal(err)
+			}
+			r.Container.ContainerID = "short"
+			if _, err := r.Normalized(action); err == nil {
+				t.Fatal("short CID accepted")
+			}
+		})
+	}
+	for name, change := range map[string]func(*ReadRequest){
+		"protocol":         func(r *ReadRequest) { r.Protocol = "old" },
+		"action":           func(r *ReadRequest) { r.Action = "volumes" },
+		"project control":  func(r *ReadRequest) { r.ProjectID = "a\nb" },
+		"negative tail":    func(r *ReadRequest) { r.TailLines = -1 },
+		"large tail":       func(r *ReadRequest) { r.TailLines = 2001 },
+		"unbounded bytes":  func(r *ReadRequest) { r.LimitBytes = 1<<20 + 1 },
+		"unexpected mount": func(r *ReadRequest) { r.Target = "/data" },
+	} {
+		t.Run(name, func(t *testing.T) {
+			r := base
+			r.Action = "logs"
+			change(&r)
+			if _, err := r.Normalized("logs"); err == nil {
+				t.Fatal("invalid log request accepted")
+			}
+		})
+	}
+}
+
+func TestFilePathsNeverNormalizeTraversalOrControlCharacters(t *testing.T) {
+	for _, value := range []string{"", ".", "a/b", "文件名.txt", "a b"} {
+		if !ValidRelativePath(value) {
+			t.Fatal("valid path rejected", value)
+		}
+	}
+	for _, value := range []string{"/etc/passwd", "../outside", "a/../../outside", "a/../outside", "a//b", `a\b`, "a\nfile", "\x00", string([]byte{0xff}), strings.Repeat("a", 4097)} {
+		if ValidRelativePath(value) {
+			t.Fatal("unsafe path accepted", value)
+		}
+	}
+	for _, value := range []string{"/", "/data/../etc", "/data/", `C:\data`, "/data\x00"} {
+		if ValidMountTarget(value) {
+			t.Fatal("unsafe mount target accepted", value)
+		}
+	}
+}

package/docker/runtime/terminal.go

@@ -0,0 +1,86 @@
+package runtime
+
+import (
+	"errors"
+	"strings"
+	"time"
+
+	"github.com/opensoha/soha/contracts/resource"
+)
+
+const TerminalProtocol = "docker-native-terminal-v1"
+const TerminalInputHeader = "X-Soha-Docker-Terminal-Input"
+
+type TerminalInput struct {
+	ExpectedContainerID string `json:"expectedContainerId"`
+	ServiceName         string `json:"serviceName"`
+	Shell               string `json:"shell,omitempty"`
+	Width               uint16 `json:"width,omitempty"`
+	Height              uint16 `json:"height,omitempty"`
+	TimeoutSeconds      int64  `json:"timeoutSeconds,omitempty"`
+}
+
+func (input TerminalInput) Normalized() (TerminalInput, error) {
+	if !containerIDPattern.MatchString(input.ExpectedContainerID) || !serviceNamePattern.MatchString(input.ServiceName) {
+		return TerminalInput{}, errors.New("terminal requires an exact service and full container ID")
+	}
+	options, err := (resource.NativeTerminalOptions{Shell: input.Shell, Width: input.Width, Height: input.Height, TimeoutSeconds: input.TimeoutSeconds}).Normalized()
+	if err != nil {
+		return TerminalInput{}, err
+	}
+	input.Shell, input.Width, input.Height, input.TimeoutSeconds = options.Shell, options.Width, options.Height, options.TimeoutSeconds
+	return input, nil
+}
+
+// The stream uses the same closed PTY frames and outcome semantics as native
+// Pod terminals. UID verification here means host/project UID labels and CID.
+type TerminalResult = resource.PodTerminalResult
+
+type TerminalLease struct {
+	Protocol        string           `json:"protocol"`
+	ID              string           `json:"id"`
+	Status          string           `json:"status"`
+	ProjectID       string           `json:"projectId"`
+	Target          ContainerBinding `json:"target"`
+	Shell           string           `json:"shell"`
+	CreatedAt       time.Time        `json:"createdAt"`
+	TicketExpiresAt time.Time        `json:"ticketExpiresAt"`
+	DeadlineAt      time.Time        `json:"deadlineAt"`
+	ClosedAt        *time.Time       `json:"closedAt,omitempty"`
+	MaxInputBytes   int64            `json:"maxInputBytes"`
+	MaxOutputBytes  int64            `json:"maxOutputBytes"`
+	Result          *TerminalResult  `json:"result,omitempty"`
+}
+
+type TerminalCreated struct {
+	Session TerminalLease `json:"session"`
+	Ticket  string        `json:"ticket"`
+}
+
+type TerminalRequest struct {
+	Protocol   string           `json:"protocol"`
+	ProjectID  string           `json:"projectId"`
+	Container  ContainerBinding `json:"container"`
+	Input      TerminalInput    `json:"input"`
+	DeadlineAt time.Time        `json:"deadlineAt"`
+}
+
+func (input TerminalRequest) Normalized(now time.Time) (TerminalRequest, error) {
+	options, err := input.Input.Normalized()
+	if err != nil || input.Protocol != TerminalProtocol || input.ProjectID == "" || !SafeText(input.ProjectID, 128) || strings.TrimSpace(input.ProjectID) != input.ProjectID || input.Container.Validate() != nil || input.Container.ContainerID != options.ExpectedContainerID || input.Container.ServiceName != options.ServiceName {
+		return TerminalRequest{}, errors.New("docker native terminal identity or protocol is invalid")
+	}
+	if !input.DeadlineAt.After(now) || input.DeadlineAt.After(now.Add(time.Duration(options.TimeoutSeconds)*time.Second)) {
+		return TerminalRequest{}, errors.New("docker native terminal deadline is invalid")
+	}
+	input.Input = options
+	return input, nil
+}
+
+type TerminalCapabilities struct {
+	Protocol          string `json:"protocol"`
+	NativePTY         bool   `json:"nativePty"`
+	MaxTimeoutSeconds int64  `json:"maxTimeoutSeconds"`
+	MaxInputBytes     int64  `json:"maxInputBytes"`
+	MaxOutputBytes    int64  `json:"maxOutputBytes"`
+}

package/docker/runtime/terminal_test.go

@@ -0,0 +1,50 @@
+package runtime
+
+import (
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestNativeTerminalInputBindsFullContainerAndSharedPTYLimits(t *testing.T) {
+	input := TerminalInput{ExpectedContainerID: strings.Repeat("a", 64), ServiceName: "owned"}
+	normal, err := input.Normalized()
+	if err != nil || normal.Shell != "/bin/sh" || normal.Width != 80 || normal.Height != 24 || normal.TimeoutSeconds != 300 {
+		t.Fatalf("defaults=%+v err=%v", normal, err)
+	}
+	for _, change := range []func(*TerminalInput){
+		func(v *TerminalInput) { v.ExpectedContainerID = "prefix" }, func(v *TerminalInput) { v.ServiceName = "../other" },
+		func(v *TerminalInput) { v.Shell = "sh -c unsafe" }, func(v *TerminalInput) { v.Width = 1001 }, func(v *TerminalInput) { v.Height = 1001 },
+		func(v *TerminalInput) { v.TimeoutSeconds = -1 }, func(v *TerminalInput) { v.TimeoutSeconds = 901 },
+	} {
+		changed := input
+		change(&changed)
+		if _, err := changed.Normalized(); err == nil {
+			t.Fatal("unsafe terminal input accepted")
+		}
+	}
+}
+
+func TestNativeTerminalRequestRequiresExactBindingAndDeadline(t *testing.T) {
+	binding, err := NewProjectBinding("6f773cfe-a522-468c-8c85-4b326d41b781", "65b279e6-ea7c-412f-a822-228349f35585")
+	if err != nil {
+		t.Fatal(err)
+	}
+	now := time.Now().UTC()
+	input := TerminalRequest{Protocol: TerminalProtocol, ProjectID: "project:owned", Container: ContainerBinding{ProjectBinding: binding, ServiceName: "owned", ContainerID: strings.Repeat("a", 64)}, Input: TerminalInput{ExpectedContainerID: strings.Repeat("a", 64), ServiceName: "owned"}, DeadlineAt: now.Add(5 * time.Minute)}
+	if _, err := input.Normalized(now); err != nil {
+		t.Fatal(err)
+	}
+	for _, change := range []func(*TerminalRequest){
+		func(v *TerminalRequest) { v.Protocol = "old" }, func(v *TerminalRequest) { v.Container.ContainerID = strings.Repeat("b", 64) },
+		func(v *TerminalRequest) { v.Container.ServiceName = "foreign" }, func(v *TerminalRequest) { v.DeadlineAt = now },
+		func(v *TerminalRequest) { v.DeadlineAt = now.Add(901 * time.Second) }, func(v *TerminalRequest) { v.ProjectID = "\nother" },
+		func(v *TerminalRequest) { v.Input.TimeoutSeconds = 1 },
+	} {
+		changed := input
+		change(&changed)
+		if _, err := changed.Normalized(now); err == nil {
+			t.Fatal("unbound or expired terminal request accepted")
+		}
+	}
+}

package/examples/relations_compat_test.go

@@ -1,7 +1,7 @@
 package examples
 
 import (
-	sdk "github.com/opensoha/soha-contracts/gen/go/sohaapi"
+	sdk "github.com/opensoha/soha/contracts/gen/go/sohaapi"
 	"testing"
 )
 

package/fixtures/json-schema/agent-protocol/valid/dsh-agent-status.json

@@ -0,0 +1,17 @@
+{
+  "runId": "run-1",
+  "callbackToken": "agent-run-token",
+  "agentId": "agent-1",
+  "status": "succeeded",
+  "payload": {
+    "summary": "Completed"
+  },
+  "events": [
+    {
+      "type": "agent.status",
+      "providerId": "dsh",
+      "providerKind": "dsh",
+      "status": "running"
+    }
+  ]
+}

package/fixtures/json-schema/docker-container-identity/invalid/name-instead-of-id.json

@@ -0,0 +1,8 @@
+{
+  "protocol": "docker-project-identity-v1",
+  "hostUid": "11111111-1111-4111-8111-111111111111",
+  "projectUid": "22222222-2222-4222-8222-222222222222",
+  "namespace": "soha-90b3f6e0fe9888c051f30305c43f6b8ab04e99944980f8715cc9",
+  "serviceName": "web",
+  "containerId": "web-1"
+}