@opensoha/contracts 0.1.26 → 0.1.29

package/openapi/spec_generated.go

@@ -5,9 +5,9 @@ package openapi
 import _ "embed"
 
 const (
-	Version    = "0.1.26"
-	YAMLSHA256 = "6d18163614e65c1f0f0439d928b65bcdd5937781ee6ae912a53526a592cbc2db"
-	JSONSHA256 = "37b9e04ece8f49eabdfe41a695ad9b28ce21d434d6a2e2b97922a9f202230c41"
+	Version    = "0.1.29"
+	YAMLSHA256 = "95ddf7a050831e3a9bae045952877b32f52d879a70e482c9c446a84f8cde4596"
+	JSONSHA256 = "4db09842ef24e3485e59e1d617f5027365eb7474de068425a50bf8a13222ad49"
 )
 
 //go:embed soha-api.yaml

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensoha/contracts",
-  "version": "0.1.26",
+  "version": "0.1.29",
   "private": false,
   "description": "Shared OpenSoha API, agent, MCP, skill, event, and auth contracts.",
   "license": "Apache-2.0",
@@ -105,7 +105,8 @@
     "./agent/personal-guest-runtime-result.schema.json": "./agent/personal-guest-runtime-result.schema.json",
     "./agent/personal-guest-tools.schema.json": "./agent/personal-guest-tools.schema.json",
     "./agent/personal-browser-network-request.schema.json": "./agent/personal-browser-network-request.schema.json",
-    "./agent/personal-browser-network-response.schema.json": "./agent/personal-browser-network-response.schema.json"
+    "./agent/personal-browser-network-response.schema.json": "./agent/personal-browser-network-response.schema.json",
+    "./endpointcontrol/protocol.schema.json": "./endpointcontrol/protocol.schema.json"
   },
   "files": [
     "delivery",
@@ -136,7 +137,9 @@
     "connectors",
     "network",
     "knowledge",
-    "memory"
+    "memory",
+    "proxytransport",
+    "endpointcontrol"
   ],
   "devDependencies": {
     "ajv": "^8.20.0",

package/proxytransport/handler.go

@@ -0,0 +1,271 @@
+// Package proxytransport supplies the HTTP CONNECT transport shared by network
+// consumers. Callers own listener lifecycle, destination policy and SOCKS routing.
+package proxytransport
+
+import (
+	"context"
+	"crypto/sha256"
+	"crypto/subtle"
+	"errors"
+	"io"
+	"net"
+	"net/http"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+)
+
+// Dial receives the authenticated transport name and original destination. A
+// consumer must resolve, authorize and pin an IP before dialing its backend.
+type Dial func(context.Context, string, string) (net.Conn, error)
+
+type Handler struct {
+	mu          sync.Mutex
+	credentials map[string][32]byte
+	dial        Dial
+	deadline    time.Time
+	closed      bool
+	connections map[net.Conn]struct{}
+}
+
+func New(credentials map[string]string, dial Dial, deadline time.Time) (*Handler, error) {
+	if len(credentials) == 0 || len(credentials) > 2048 || dial == nil || !deadline.After(time.Now()) || deadline.After(time.Now().Add(5*time.Minute)) {
+		return nil, errors.New("invalid proxy transport dependencies or lease")
+	}
+	h := &Handler{credentials: map[string][32]byte{}, dial: dial, deadline: deadline.UTC(), connections: map[net.Conn]struct{}{}}
+	for user, password := range credentials {
+		if user == "" || len(user) > 128 || len(password) < 32 {
+			return nil, errors.New("invalid proxy transport credential")
+		}
+		h.credentials[user] = sha256.Sum256([]byte(password))
+	}
+	return h, nil
+}
+
+func (h *Handler) Refresh(deadline time.Time) error {
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	if h.closed || !deadline.After(time.Now()) || deadline.After(time.Now().Add(5*time.Minute)) {
+		return errors.New("proxy transport lease is inactive")
+	}
+	deadline = deadline.UTC()
+	h.deadline = deadline
+	for conn := range h.connections {
+		if err := conn.SetDeadline(deadline); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func (h *Handler) Close() error {
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	if h.closed {
+		return nil
+	}
+	h.closed = true
+	var result error
+	for conn := range h.connections {
+		if err := conn.Close(); err != nil && !errors.Is(err, net.ErrClosed) {
+			result = errors.Join(result, err)
+		}
+	}
+	return result
+}
+
+func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	user, ok := h.authenticate(r)
+	if !ok {
+		w.Header().Set("Proxy-Authenticate", `Basic realm="Soha managed transport"`)
+		http.Error(w, "proxy authentication required", http.StatusProxyAuthRequired)
+		return
+	}
+	if r.Method == http.MethodConnect {
+		h.connect(w, r, user)
+		return
+	}
+	if r.URL.Scheme != "http" || r.URL.Host == "" || r.Host != r.URL.Host || r.URL.User != nil || r.Header.Get("Upgrade") != "" {
+		http.Error(w, "unsupported proxy request", http.StatusBadRequest)
+		return
+	}
+	h.forward(w, r, user)
+}
+
+func (h *Handler) authenticate(r *http.Request) (string, bool) {
+	values := r.Header.Values("Proxy-Authorization")
+	if len(values) != 1 {
+		return "", false
+	}
+	copy := r.Clone(r.Context())
+	copy.Header = make(http.Header)
+	copy.Header.Set("Authorization", values[0])
+	user, password, ok := copy.BasicAuth()
+	if !ok {
+		return "", false
+	}
+	expected, exists := h.credentials[user]
+	actual := sha256.Sum256([]byte(password))
+	return user, exists && subtle.ConstantTimeCompare(expected[:], actual[:]) == 1
+}
+
+func (h *Handler) open(ctx context.Context, user, address string) (net.Conn, error) {
+	host, rawPort, err := net.SplitHostPort(address)
+	if err != nil || host == "" || len(host) > 253 {
+		return nil, errors.New("invalid proxy target")
+	}
+	port, err := strconv.Atoi(rawPort)
+	if err != nil || port < 1 || port > 65535 {
+		return nil, errors.New("invalid proxy target port")
+	}
+	h.mu.Lock()
+	until, closed := h.deadline, h.closed
+	h.mu.Unlock()
+	if closed || !until.After(time.Now()) {
+		return nil, errors.New("proxy transport lease expired")
+	}
+	ctx, cancel := context.WithDeadline(ctx, until)
+	defer cancel()
+	conn, err := h.dial(ctx, user, net.JoinHostPort(host, rawPort))
+	if err != nil {
+		return nil, err
+	}
+	if err := conn.SetDeadline(until); err != nil {
+		_ = conn.Close()
+		return nil, err
+	}
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	if h.closed || !h.deadline.After(time.Now()) || len(h.connections) >= 4096 {
+		_ = conn.Close()
+		return nil, errors.New("proxy transport was closed or reached its limit")
+	}
+	if err := conn.SetDeadline(h.deadline); err != nil {
+		_ = conn.Close()
+		return nil, err
+	}
+	h.connections[conn] = struct{}{}
+	return &trackedConn{Conn: conn, handler: h}, nil
+}
+
+func (h *Handler) Ready() bool {
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	return !h.closed && h.deadline.After(time.Now())
+}
+
+type trackedConn struct {
+	net.Conn
+	handler *Handler
+}
+
+func (c *trackedConn) Close() error {
+	c.handler.mu.Lock()
+	delete(c.handler.connections, c.Conn)
+	c.handler.mu.Unlock()
+	return c.Conn.Close()
+}
+
+func (h *Handler) connect(w http.ResponseWriter, r *http.Request, user string) {
+	if r.URL.Host != "" && r.URL.Host != r.Host || r.URL.User != nil {
+		http.Error(w, "ambiguous proxy target", http.StatusBadRequest)
+		return
+	}
+	upstream, err := h.open(r.Context(), user, r.Host)
+	if err != nil {
+		http.Error(w, "proxy target unavailable", http.StatusBadGateway)
+		return
+	}
+	defer func() { _ = upstream.Close() }()
+	hijacker, ok := w.(http.Hijacker)
+	if !ok {
+		http.Error(w, "CONNECT unavailable", http.StatusInternalServerError)
+		return
+	}
+	client, buffer, err := hijacker.Hijack()
+	if err != nil {
+		return
+	}
+	defer func() { _ = client.Close() }()
+	h.mu.Lock()
+	closed := h.closed || !h.deadline.After(time.Now()) || len(h.connections) >= 4096
+	if !closed {
+		if err := client.SetDeadline(h.deadline); err != nil {
+			closed = true
+		} else {
+			h.connections[client] = struct{}{}
+		}
+	}
+	h.mu.Unlock()
+	defer func() { h.mu.Lock(); delete(h.connections, client); h.mu.Unlock() }()
+	if closed {
+		return
+	}
+
+	if _, err := buffer.WriteString("HTTP/1.1 200 Connection Established\r\n\r\n"); err != nil {
+		return
+	}
+	if buffer.Flush() != nil {
+		return
+	}
+	done := make(chan struct{})
+	go func() { defer close(done); _, _ = io.Copy(upstream, buffer); _ = upstream.Close() }()
+	_, _ = io.Copy(client, upstream)
+	_ = client.Close()
+	_ = upstream.Close()
+	<-done
+}
+
+func (h *Handler) forward(w http.ResponseWriter, r *http.Request, user string) {
+	h.mu.Lock()
+	until, closed := h.deadline, h.closed
+	h.mu.Unlock()
+	if closed || !until.After(time.Now()) {
+		http.Error(w, "proxy lease expired", http.StatusServiceUnavailable)
+		return
+	}
+	control := http.NewResponseController(w)
+	if control.SetReadDeadline(until) != nil || control.SetWriteDeadline(until) != nil {
+		http.Error(w, "bounded proxy transport unavailable", http.StatusServiceUnavailable)
+		return
+	}
+	ctx, cancel := context.WithDeadline(r.Context(), until)
+	defer cancel()
+	request := r.Clone(ctx)
+	request.RequestURI = ""
+	request.Header = request.Header.Clone()
+	removeHopHeaders(request.Header)
+	transport := &http.Transport{Proxy: nil, DialContext: func(ctx context.Context, network, address string) (net.Conn, error) {
+		if network != "tcp" {
+			return nil, errors.New("unsupported proxy transport")
+		}
+		return h.open(ctx, user, address)
+	}, DisableKeepAlives: true, ResponseHeaderTimeout: 30 * time.Second}
+	defer transport.CloseIdleConnections()
+	response, err := transport.RoundTrip(request)
+	if err != nil {
+		http.Error(w, "proxy target unavailable", http.StatusBadGateway)
+		return
+	}
+	defer func() { _ = response.Body.Close() }()
+	removeHopHeaders(response.Header)
+	for name, values := range response.Header {
+		for _, value := range values {
+			w.Header().Add(name, value)
+		}
+	}
+	w.WriteHeader(response.StatusCode)
+	_, _ = io.Copy(w, response.Body)
+}
+
+func removeHopHeaders(header http.Header) {
+	for _, line := range header.Values("Connection") {
+		for _, name := range strings.Split(line, ",") {
+			header.Del(strings.TrimSpace(name))
+		}
+	}
+	for _, name := range []string{"Connection", "Proxy-Connection", "Keep-Alive", "Proxy-Authenticate", "Proxy-Authorization", "TE", "Trailer", "Transfer-Encoding", "Upgrade"} {
+		header.Del(name)
+	}
+}

package/proxytransport/probe.go

@@ -0,0 +1,30 @@
+package proxytransport
+
+import (
+	"bufio"
+	"io"
+	"net"
+	"net/http"
+	"time"
+)
+
+// ProbeConnection returns a bounded, local HTTP responder used only after a
+// consumer has matched its unpredictable, private health-probe hostname.
+// It never opens a network socket or forwards data to a real destination.
+func ProbeConnection() net.Conn {
+	client, server := net.Pipe()
+	go func() {
+		defer func() { _ = server.Close() }()
+		_ = server.SetDeadline(time.Now().Add(2 * time.Second))
+		request, err := http.ReadRequest(bufio.NewReader(io.LimitReader(server, 16<<10)))
+		if err != nil {
+			return
+		}
+		_ = request.Body.Close()
+		if request.Method != http.MethodGet {
+			return
+		}
+		_, _ = io.WriteString(server, "HTTP/1.1 204 No Content\r\nConnection: close\r\n\r\n")
+	}()
+	return client
+}

package/proxytransport/scope.go

@@ -0,0 +1,89 @@
+package proxytransport
+
+import (
+	"context"
+	"errors"
+	"net"
+	"net/netip"
+	"strings"
+)
+
+type Scope struct {
+	prefixes []netip.Prefix
+	hosts    []string
+}
+
+func NewScope(cidrs, hosts []string) (*Scope, error) {
+	if len(cidrs) > 4096 || len(hosts) > 2048 {
+		return nil, errors.New("proxy destination scope exceeds its limit")
+	}
+	scope := &Scope{hosts: append([]string(nil), hosts...)}
+	for _, raw := range cidrs {
+		prefix, err := netip.ParsePrefix(raw)
+		if err != nil || !prefix.Addr().IsGlobalUnicast() || prefix.Addr().Is4In6() || prefix.Bits() == 0 || prefix != prefix.Masked() || prefix.String() != raw {
+			return nil, errors.New("invalid proxy destination prefix")
+		}
+		scope.prefixes = append(scope.prefixes, prefix)
+	}
+	for _, host := range hosts {
+		if !validHost(host) || strings.ToLower(host) != host {
+			return nil, errors.New("invalid protected hostname")
+		}
+	}
+	return scope, nil
+}
+
+// Resolve checks every answer before choosing one. Returning a literal IP to a
+// transport prevents a second, remote DNS result from changing the destination.
+func (s *Scope) Resolve(ctx context.Context, host string) (netip.Addr, error) {
+	host = strings.ToLower(strings.TrimSuffix(host, "."))
+	for _, protected := range s.hosts {
+		if host == protected || strings.HasSuffix(host, "."+protected) {
+			return netip.Addr{}, errors.New("protected proxy hostname")
+		}
+	}
+	addresses := []netip.Addr{}
+	if address, err := netip.ParseAddr(host); err == nil {
+		addresses = append(addresses, address)
+	} else {
+		if !validHost(host) {
+			return netip.Addr{}, errors.New("invalid proxy hostname")
+		}
+		var err error
+		addresses, err = net.DefaultResolver.LookupNetIP(ctx, "ip", host)
+		if err != nil {
+			return netip.Addr{}, errors.New("proxy DNS unavailable")
+		}
+	}
+	if len(addresses) == 0 || len(addresses) > 32 {
+		return netip.Addr{}, errors.New("invalid proxy DNS answer count")
+	}
+	for _, address := range addresses {
+		if !address.IsGlobalUnicast() || address.Is4In6() {
+			return netip.Addr{}, errors.New("unsafe proxy address")
+		}
+		for _, prefix := range s.prefixes {
+			if prefix.Contains(address) {
+				return netip.Addr{}, errors.New("protected proxy address")
+			}
+		}
+	}
+	return addresses[0], nil
+}
+
+func validHost(host string) bool {
+	if len(host) == 0 || len(host) > 253 {
+		return false
+	}
+	for _, label := range strings.Split(host, ".") {
+		if len(label) == 0 || len(label) > 63 || label[0] == '-' || label[len(label)-1] == '-' {
+			return false
+		}
+		for _, char := range label {
+			if char != '-' && (char < 'a' || char > 'z') && (char < '0' || char > '9') {
+				return false
+			}
+		}
+	}
+	return true
+}

package/proxytransport/transport_test.go

@@ -0,0 +1,60 @@
+package proxytransport
+
+import (
+	"context"
+	"net"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+)
+
+func TestScopeBlocksProtectedIPv4AndIPv6AndRetainsUnprotectedPrivateUpstreams(t *testing.T) {
+	scope, err := NewScope([]string{"10.20.0.0/16", "fd20::/64"}, []string{"payroll.example.internal"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, host := range []string{"10.20.1.1", "fd20::10", "payroll.example.internal", "alias.payroll.example.internal", "127.0.0.1", "::1"} {
+		if _, err := scope.Resolve(context.Background(), host); err == nil {
+			t.Fatalf("unsafe destination %s accepted", host)
+		}
+	}
+	for _, host := range []string{"10.30.1.1", "fd30::10"} {
+		if _, err := scope.Resolve(context.Background(), host); err != nil {
+			t.Fatalf("unprotected enterprise upstream %s rejected: %v", host, err)
+		}
+	}
+}
+func TestGuardRejectsAmbiguousHTTPAuthorityBeforeDial(t *testing.T) {
+	dialed := false
+	handler, err := New(map[string]string{"node": "0123456789abcdef0123456789abcdef"}, func(context.Context, string, string) (net.Conn, error) { dialed = true; return nil, nil }, time.Now().Add(time.Minute))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = handler.Close() }()
+	request := httptest.NewRequest(http.MethodGet, "http://public.example/", nil)
+	request.Host = "protected.internal"
+	request.SetBasicAuth("node", "0123456789abcdef0123456789abcdef")
+	request.Header.Set("Proxy-Authorization", request.Header.Get("Authorization"))
+	request.Header.Del("Authorization")
+	response := httptest.NewRecorder()
+	handler.ServeHTTP(response, request)
+	if response.Code != http.StatusBadRequest || dialed {
+		t.Fatalf("ambiguous request status=%d dialed=%t", response.Code, dialed)
+	}
+}
+func TestGuardRejectsExpiredRenewalAndCannotReopenAfterClose(t *testing.T) {
+	handler, err := New(map[string]string{"node": "0123456789abcdef0123456789abcdef"}, func(context.Context, string, string) (net.Conn, error) { return nil, nil }, time.Now().Add(time.Minute))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if handler.Refresh(time.Now().Add(-time.Second)) == nil {
+		t.Fatal("expired renewal accepted")
+	}
+	if err := handler.Close(); err != nil {
+		t.Fatal(err)
+	}
+	if handler.Ready() || handler.Refresh(time.Now().Add(time.Minute)) == nil {
+		t.Fatal("closed transport resurrected")
+	}
+}

package/resource/agent_profiles.go

@@ -8,22 +8,14 @@ func KubernetesAgentProfileActions(profile string) ([]string, error) {
 	switch profile {
 	case "read-only":
 		return []string{"platform.custom_resources.list"}, nil
-	case "workbench":
+	case "workbench", "legacy":
 		return append([]string(nil), kubernetesWorkbenchActions[:]...), nil
-	case "legacy":
-		actions := make([]string, 0, len(kubernetesWorkbenchActions))
-		for _, action := range kubernetesWorkbenchActions {
-			if action != "platform.helm_releases.install" && action != "platform.helm_releases.values_update" && action != "platform.helm_releases.delete" && action != "platform.helm_releases.rollback" {
-				actions = append(actions, action)
-			}
-		}
-		return actions, nil
 	default:
 		return nil, fmt.Errorf("unknown Kubernetes Agent action profile")
 	}
 }
 
-// KubernetesAgentActions lists implemented platform actions, including separately opted-in CRD deletion.
+// KubernetesAgentActions lists implemented platform actions, including separately opted-in mutations.
 func KubernetesAgentActions() []string {
 	actions := make([]string, 0, len(kubernetesWorkbenchActions))
 	for _, action := range kubernetesWorkbenchActions {
@@ -31,7 +23,13 @@ func KubernetesAgentActions() []string {
 			actions = append(actions, action)
 		}
 	}
-	return append(actions, "platform.crds.delete")
+	return append(actions,
+		"platform.helm_releases.install",
+		"platform.helm_releases.values_update",
+		"platform.helm_releases.delete",
+		"platform.helm_releases.rollback",
+		"platform.crds.delete",
+	)
 }
 
 var kubernetesWorkbenchActions = [...]string{
@@ -54,9 +52,5 @@ var kubernetesWorkbenchActions = [...]string{
 	"platform.port_forwards.create",
 	"platform.port_forwards.tunnel",
 	"platform.port_forwards.delete",
-	"platform.helm_releases.install",
-	"platform.helm_releases.values_update",
-	"platform.helm_releases.delete",
-	"platform.helm_releases.rollback",
 	"runtime.execution_tasks.cancel",
 }

package/resource/agent_profiles_test.go

@@ -10,7 +10,7 @@ func TestKubernetesAgentProfilesKeepPermissionsExplicit(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	for _, action := range []string{"platform.nodes.drain", "platform.resources.apply", "platform.resources.create", "platform.resources.delete", "platform.helm_releases.rollback", "platform.port_forwards.tunnel"} {
+	for _, action := range []string{"platform.nodes.drain", "platform.resources.apply", "platform.resources.create", "platform.resources.delete", "platform.port_forwards.tunnel"} {
 		if !slices.Contains(workbench, action) {
 			t.Fatalf("missing workbench action %s", action)
 		}
@@ -19,8 +19,14 @@ func TestKubernetesAgentProfilesKeepPermissionsExplicit(t *testing.T) {
 		t.Fatal("workbench must not opt into unrestricted or CRD deletion actions")
 	}
 	legacy, _ := KubernetesAgentProfileActions("legacy")
-	if slices.Contains(legacy, "platform.helm_releases.install") {
-		t.Fatal("legacy installation permissions expanded")
+	if !slices.Equal(workbench, legacy) {
+		t.Fatal("legacy action set changed")
+	}
+	implemented := KubernetesAgentActions()
+	for _, action := range []string{"platform.helm_releases.install", "platform.helm_releases.values_update", "platform.helm_releases.delete", "platform.helm_releases.rollback"} {
+		if slices.Contains(workbench, action) || !slices.Contains(implemented, action) {
+			t.Fatalf("Helm mutation %s must require explicit opt-in", action)
+		}
 	}
 	readOnly, _ := KubernetesAgentProfileActions("read-only")
 	if !slices.Equal(readOnly, []string{"platform.custom_resources.list"}) {

package/resource/custom_graph_page.go

@@ -0,0 +1,18 @@
+package resource
+
+import "encoding/json"
+
+// CustomResourceGraphObjectPath is relative to the authenticated Agent platform API.
+const CustomResourceGraphObjectPath = "/extensions/custom-resources/graph-object"
+
+type CustomResourceGraphObjectRequest struct {
+	Definition CRDResourceDefinition `json:"definition"`
+	Namespace  string                `json:"namespace"`
+	Name       string                `json:"name"`
+}
+
+// CustomResourceGraphPage contains only observed GVK and relationship metadata.
+type CustomResourceGraphPage struct {
+	Items     []json.RawMessage `json:"items"`
+	Truncated bool              `json:"truncated"`
+}