@opensoha/contracts 0.1.27 → 0.2.0

package/resource/network_topology.go

@@ -1,6 +1,7 @@
 package resource
 
 const (
+	NetworkTopologyNamedRootFeature = "network.topology.named-root.v1"
 	NetworkTopologySnapshotFeature  = "network.topology.snapshot.v1"
 	NetworkTopologyGatewayL4Feature = "network.topology.gateway-l4.v1"
 	NetworkTopologyMaxQueries       = 64
@@ -36,6 +37,8 @@ type NetworkTopologyGraphEdge struct {
 	ResolutionState string       `json:"resolutionState"`
 	Protocol        string       `json:"protocol,omitempty"`
 	Port            string       `json:"port,omitempty"`
+	SectionName     string       `json:"sectionName,omitempty"`
+	FieldPath       string       `json:"fieldPath,omitempty"`
 	Weight          *int64       `json:"weight,omitempty"`
 	TotalWeight     *int64       `json:"totalWeight,omitempty"`
 	MirrorPercent   *float64     `json:"mirrorPercent,omitempty"`
@@ -74,6 +77,7 @@ type NetworkTopologyCondition struct {
 }
 
 type NetworkTopologyCoverage struct {
+	Name           string   `json:"name,omitempty"`
 	Provider       string   `json:"provider"`
 	SourceID       string   `json:"sourceId"`
 	State          string   `json:"state"`
@@ -87,6 +91,7 @@ type NetworkTopologyCoverage struct {
 
 // Snapshot queries name a fixed source, never a caller-supplied GVR or field path.
 type NetworkTopologySourceQuery struct {
+	Name      string `json:"name,omitempty"`
 	SourceID  string `json:"sourceId"`
 	Namespace string `json:"namespace,omitempty"`
 }
@@ -120,6 +125,10 @@ type NetworkTopologySourceDefinition struct {
 }
 
 var networkTopologySources = [...]NetworkTopologySourceDefinition{
+	{ID: "kubernetes.networkpolicies", Provider: "kubernetes", CRDResourceDefinition: CRDResourceDefinition{Kind: "NetworkPolicy", Group: "networking.k8s.io", Version: "v1", Resource: "networkpolicies", Namespaced: true}},
+	{ID: "kubernetes.namespaces", Provider: "kubernetes", CRDResourceDefinition: CRDResourceDefinition{Kind: "Namespace", Version: "v1", Resource: "namespaces"}},
+	{ID: "kubernetes.configmaps", Provider: "kubernetes", CRDResourceDefinition: CRDResourceDefinition{Kind: "ConfigMap", Version: "v1", Resource: "configmaps", Namespaced: true}},
+	{ID: "gateway.backendtlspolicies", Provider: "gateway", FallbackVersion: "v1alpha3", CRDResourceDefinition: CRDResourceDefinition{Kind: "BackendTLSPolicy", Group: "gateway.networking.k8s.io", Version: "v1", Resource: "backendtlspolicies", Namespaced: true}},
 	{ID: "kubernetes.services", Provider: "kubernetes", CRDResourceDefinition: CRDResourceDefinition{Kind: "Service", Version: "v1", Resource: "services", Namespaced: true}},
 	{ID: "kubernetes.pods", Provider: "kubernetes", CRDResourceDefinition: CRDResourceDefinition{Kind: "Pod", Version: "v1", Resource: "pods", Namespaced: true}},
 	{ID: "kubernetes.endpointslices", Provider: "kubernetes", CRDResourceDefinition: CRDResourceDefinition{Kind: "EndpointSlice", Group: "discovery.k8s.io", Version: "v1", Resource: "endpointslices", Namespaced: true}},
@@ -164,3 +173,16 @@ func LookupNetworkTopologySource(id string) (NetworkTopologySourceDefinition, bo
 	}
 	return NetworkTopologySourceDefinition{}, false
 }
+
+// NetworkTopologySourceVersions is the explicit served-version allowlist. Legacy
+// BackendTLSPolicy v1alpha2 uses targetRef rather than targetRefs.
+func NetworkTopologySourceVersions(d NetworkTopologySourceDefinition) []string {
+	versions := []string{d.Version}
+	if d.FallbackVersion != "" {
+		versions = append(versions, d.FallbackVersion)
+	}
+	if d.ID == "gateway.backendtlspolicies" {
+		versions = append(versions, "v1alpha2")
+	}
+	return versions
+}

package/resource/network_topology_projection.go

@@ -124,28 +124,32 @@ func redactTopologyMatches(value any, key string) {
 }
 
 var topologyProjectionPaths = map[string][]string{
-	"kubernetes.services":       strings.Fields("spec.type spec.externalName spec.clusterIP spec.selector.* spec.ports.name spec.ports.port spec.ports.targetPort spec.ports.protocol spec.publishNotReadyAddresses"),
-	"kubernetes.pods":           strings.Fields("metadata.labels.* status.phase status.conditions.type status.conditions.status"),
-	"kubernetes.endpointslices": strings.Fields("metadata.labels.* addressType ports.name ports.port ports.protocol endpoints.addresses endpoints.conditions.ready endpoints.conditions.serving endpoints.conditions.terminating endpoints.targetRef.kind endpoints.targetRef.namespace endpoints.targetRef.name endpoints.targetRef.uid"),
-	"kubernetes.ingresses":      strings.Fields("spec.ingressClassName spec.defaultBackend.service.name spec.defaultBackend.service.port.name spec.defaultBackend.service.port.number spec.defaultBackend.resource.kind spec.rules.host spec.rules.http.paths.path spec.rules.http.paths.pathType spec.rules.http.paths.backend.service.name spec.rules.http.paths.backend.service.port.name spec.rules.http.paths.backend.service.port.number spec.rules.http.paths.backend.resource.kind spec.tls.hosts"),
-	"kubernetes.ingressclasses": strings.Fields("spec.controller"),
-	"gateway.gateways":          strings.Fields("spec.gatewayClassName spec.listeners.name spec.listeners.port spec.listeners.protocol spec.listeners.hostname spec.listeners.allowedRoutes.namespaces.from spec.listeners.allowedRoutes.namespaces.selector.matchLabels.* spec.listeners.allowedRoutes.kinds.kind spec.listeners.allowedRoutes.kinds.group spec.listeners.tls.mode"),
-	"gateway.gatewayclasses":    strings.Fields("spec.controllerName"),
-	"gateway.httproutes":        gatewayTopologyPaths(),
-	"gateway.grpcroutes":        gatewayTopologyPaths(),
-	"gateway.tcproutes":         gatewayL4TopologyPaths(),
-	"gateway.tlsroutes":         gatewayL4TopologyPaths(),
-	"gateway.udproutes":         gatewayL4TopologyPaths(),
-	"gateway.referencegrants":   strings.Fields("spec.from.group spec.from.kind spec.from.namespace spec.to.group spec.to.kind spec.to.name"),
-	"traefik.ingressroutes":     traefikTopologyPaths(),
-	"traefik.ingressroutetcps":  traefikTopologyPaths(),
-	"traefik.ingressrouteudps":  traefikTopologyPaths(),
-	"traefik.traefikservices":   strings.Fields("spec.weighted.services.name spec.weighted.services.namespace spec.weighted.services.kind spec.weighted.services.port spec.weighted.services.weight spec.mirroring.name spec.mirroring.namespace spec.mirroring.kind spec.mirroring.port spec.mirroring.mirrors.name spec.mirroring.mirrors.namespace spec.mirroring.mirrors.kind spec.mirroring.mirrors.port spec.mirroring.mirrors.percent"),
-	"traefik.middlewares":       strings.Fields("spec.chain.middlewares.name spec.chain.middlewares.namespace"),
-	"traefik.middlewaretcps":    strings.Fields("spec.chain.middlewares.name spec.chain.middlewares.namespace"),
-	"apisix.apisixroutes":       apisixTopologyPaths(),
-	"apisix.apisixupstreams":    strings.Fields("spec.scheme spec.loadbalancer.type spec.externalNodes.type spec.externalNodes.name spec.externalNodes.port spec.externalNodes.weight spec.subsets.name spec.subsets.labels.*"),
-	"apisix.apisixtls":          strings.Fields("spec.hosts spec.secret.name spec.secret.namespace"),
+	"kubernetes.namespaces":      strings.Fields("metadata.labels.*"),
+	"kubernetes.configmaps":      {},
+	"kubernetes.networkpolicies": networkPolicyTopologyPaths(),
+	"gateway.backendtlspolicies": strings.Fields("spec.targetRefs.group spec.targetRefs.kind spec.targetRefs.name spec.targetRefs.sectionName spec.targetRef.group spec.targetRef.kind spec.targetRef.name spec.targetRef.sectionName spec.validation.caCertificateRefs.group spec.validation.caCertificateRefs.kind spec.validation.caCertificateRefs.name"),
+	"kubernetes.services":        strings.Fields("spec.type spec.externalName spec.clusterIP spec.selector.* spec.ports.name spec.ports.port spec.ports.targetPort spec.ports.protocol spec.publishNotReadyAddresses"),
+	"kubernetes.pods":            strings.Fields("metadata.labels.* status.phase status.conditions.type status.conditions.status"),
+	"kubernetes.endpointslices":  strings.Fields("metadata.labels.* addressType ports.name ports.port ports.protocol endpoints.addresses endpoints.conditions.ready endpoints.conditions.serving endpoints.conditions.terminating endpoints.targetRef.apiVersion endpoints.targetRef.kind endpoints.targetRef.namespace endpoints.targetRef.name endpoints.targetRef.uid"),
+	"kubernetes.ingresses":       strings.Fields("spec.ingressClassName spec.defaultBackend.service.name spec.defaultBackend.service.port.name spec.defaultBackend.service.port.number spec.defaultBackend.resource.kind spec.rules.host spec.rules.http.paths.path spec.rules.http.paths.pathType spec.rules.http.paths.backend.service.name spec.rules.http.paths.backend.service.port.name spec.rules.http.paths.backend.service.port.number spec.rules.http.paths.backend.resource.kind spec.tls.hosts spec.tls.secretName"),
+	"kubernetes.ingressclasses":  strings.Fields("spec.controller spec.parameters.apiGroup spec.parameters.kind spec.parameters.name spec.parameters.namespace spec.parameters.scope"),
+	"gateway.gateways":           strings.Fields("spec.gatewayClassName spec.listeners.name spec.listeners.port spec.listeners.protocol spec.listeners.hostname spec.listeners.allowedRoutes.namespaces.from spec.listeners.allowedRoutes.namespaces.selector.matchLabels.* spec.listeners.allowedRoutes.kinds.kind spec.listeners.allowedRoutes.kinds.group spec.listeners.tls.mode spec.listeners.tls.certificateRefs.group spec.listeners.tls.certificateRefs.kind spec.listeners.tls.certificateRefs.name spec.listeners.tls.certificateRefs.namespace spec.listeners.allowedRoutes.namespaces.selector.matchExpressions.key spec.listeners.allowedRoutes.namespaces.selector.matchExpressions.operator spec.listeners.allowedRoutes.namespaces.selector.matchExpressions.values"),
+	"gateway.gatewayclasses":     strings.Fields("spec.controllerName spec.parametersRef.group spec.parametersRef.kind spec.parametersRef.name spec.parametersRef.namespace"),
+	"gateway.httproutes":         gatewayTopologyPaths(),
+	"gateway.grpcroutes":         gatewayTopologyPaths(),
+	"gateway.tcproutes":          gatewayL4TopologyPaths(),
+	"gateway.tlsroutes":          gatewayL4TopologyPaths(),
+	"gateway.udproutes":          gatewayL4TopologyPaths(),
+	"gateway.referencegrants":    strings.Fields("spec.from.group spec.from.kind spec.from.namespace spec.to.group spec.to.kind spec.to.name"),
+	"traefik.ingressroutes":      traefikTopologyPaths(),
+	"traefik.ingressroutetcps":   traefikTopologyPaths(),
+	"traefik.ingressrouteudps":   traefikTopologyPaths(),
+	"traefik.traefikservices":    strings.Fields("spec.weighted.services.name spec.weighted.services.namespace spec.weighted.services.kind spec.weighted.services.port spec.weighted.services.weight spec.mirroring.name spec.mirroring.namespace spec.mirroring.kind spec.mirroring.port spec.mirroring.mirrors.name spec.mirroring.mirrors.namespace spec.mirroring.mirrors.kind spec.mirroring.mirrors.port spec.mirroring.mirrors.percent"),
+	"traefik.middlewares":        strings.Fields("spec.chain.middlewares.name spec.chain.middlewares.namespace"),
+	"traefik.middlewaretcps":     strings.Fields("spec.chain.middlewares.name spec.chain.middlewares.namespace"),
+	"apisix.apisixroutes":        apisixTopologyPaths(),
+	"apisix.apisixupstreams":     strings.Fields("spec.scheme spec.loadbalancer.type spec.externalNodes.type spec.externalNodes.name spec.externalNodes.port spec.externalNodes.weight spec.subsets.name spec.subsets.labels.*"),
+	"apisix.apisixtls":           strings.Fields("spec.hosts spec.secret.name spec.secret.namespace"),
 }
 
 func gatewayTopologyPaths() []string {
@@ -206,3 +210,13 @@ func topologyMiddlewareTypes(input map[string]any) []string {
 	sort.Strings(result)
 	return result
 }
+
+func networkPolicyTopologyPaths() []string {
+	paths := strings.Fields("spec.podSelector.matchLabels.* spec.podSelector.matchExpressions.key spec.podSelector.matchExpressions.operator spec.podSelector.matchExpressions.values spec.policyTypes")
+	for _, direction := range []string{"ingress.from", "egress.to"} {
+		for _, field := range strings.Fields("podSelector.matchLabels.* podSelector.matchExpressions.key podSelector.matchExpressions.operator podSelector.matchExpressions.values namespaceSelector.matchLabels.* namespaceSelector.matchExpressions.key namespaceSelector.matchExpressions.operator namespaceSelector.matchExpressions.values ipBlock.cidr ipBlock.except") {
+			paths = append(paths, "spec."+direction+"."+field)
+		}
+	}
+	return paths
+}

package/resource/network_topology_projection_test.go

@@ -11,6 +11,10 @@ func TestTopologyProjectionExcludesCredentialsAndPreservesAlternatives(t *testin
 		source, input string
 		keep          []string
 	}{
+		{"kubernetes.configmaps", `{"metadata":{"name":"ca","uid":"ca-uid","annotations":{"key":"secret-value"}},"data":{"ca.crt":"secret-value"},"binaryData":{"key":"secret-value"}}`, []string{"ca-uid"}},
+		{"kubernetes.namespaces", `{"metadata":{"name":"team","labels":{"access":"permitted"},"annotations":{"token":"secret-value"}}}`, []string{"permitted"}},
+		{"kubernetes.networkpolicies", `{"spec":{"podSelector":{"matchLabels":{"app":"web"}},"ingress":[{"from":[{"namespaceSelector":{"matchLabels":{"role":"client"}},"podSelector":{"matchExpressions":[{"key":"tier","operator":"In","values":["frontend"]}]}},{"ipBlock":{"cidr":"10.0.0.0/8","except":["10.1.0.0/16"]}}]}]},"data":"secret-value"}`, []string{"frontend", "10.1.0.0/16"}},
+		{"gateway.backendtlspolicies", `{"spec":{"targetRefs":[{"group":"","kind":"Service","name":"web","sectionName":"https"}],"targetRef":{"kind":"Service","name":"legacy"},"validation":{"caCertificateRefs":[{"kind":"ConfigMap","name":"ca"}],"privateKey":"secret-value"}}}`, []string{"https", "legacy", "ca"}},
 		{"kubernetes.pods", `{"metadata":{"name":"p","namespace":"n","annotations":{"token":"secret-value"},"labels":{"app":"web"}},"spec":{"containers":[{"env":[{"value":"secret-value"}]}]},"status":{"phase":"Running"}}`, []string{"Running", "web"}},
 		{"gateway.httproutes", `{"metadata":{"name":"r"},"spec":{"rules":[{"matches":[{"method":"GET","headers":[{"name":"Authorization","value":"secret-value"}],"queryParams":[{"name":"token","value":"secret-value"}]}],"backendRefs":[{"name":"web","weight":0,"port":80}]}]}}`, []string{"GET", "[redacted]", "\"weight\":0"}},
 		{"gateway.tcproutes", `{"spec":{"parentRefs":[{"name":"gw","sectionName":"tcp","port":9000}],"rules":[{"backendRefs":[{"name":"web","port":9000,"weight":0}],"filters":[{"secret":"secret-value"}]}]}}`, []string{"tcp", "9000", "\"weight\":0"}},

package/resource/network_topology_test.go

@@ -49,3 +49,23 @@ func TestTopologySourcesKeepSupportedVersionsAndDedicatedKindsExplicit(t *testin
 		t.Fatal("source allowlist is mutable by callers")
 	}
 }
+
+func TestNetworkTopologyNamedQueriesRejectUnsafeIdentity(t *testing.T) {
+	for _, query := range []NetworkTopologySourceQuery{
+		{SourceID: "kubernetes.services", Namespace: "team", Name: "../secret"},
+		{SourceID: "traefik.ingressroutes", Namespace: "team", Name: "route"},
+		{SourceID: "gateway.tcproutes", Namespace: "team", Name: "route"},
+		{SourceID: "kubernetes.services", Name: "service"},
+		{SourceID: "kubernetes.services", Namespace: "team", Name: "service/name"},
+		{SourceID: "kubernetes.services", Namespace: "team", Name: "service?watch=true"},
+		{SourceID: "kubernetes.ingressclasses", Namespace: "team", Name: "class"},
+	} {
+		if err := ValidateNetworkTopologySnapshotRequest(NetworkTopologySnapshotRequest{Queries: []NetworkTopologySourceQuery{query}}); err == nil {
+			t.Fatalf("unsafe named query accepted: %+v", query)
+		}
+	}
+	valid := NetworkTopologySnapshotRequest{Queries: []NetworkTopologySourceQuery{{SourceID: "kubernetes.services", Namespace: "team", Name: "service"}, {SourceID: "kubernetes.services", Namespace: "team"}}}
+	if err := ValidateNetworkTopologySnapshotRequest(valid); err != nil {
+		t.Fatalf("named and list queries must coexist: %v", err)
+	}
+}

package/resource/network_topology_validation.go

@@ -6,6 +6,8 @@ import (
 	"regexp"
 )
 
+var topologyNamePattern = regexp.MustCompile(`^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$`)
+
 var topologyNamespacePattern = regexp.MustCompile(`^[a-z0-9]([a-z0-9-]*[a-z0-9])?$`)
 
 func ValidateNetworkTopologySnapshotRequest(request NetworkTopologySnapshotRequest) error {
@@ -19,6 +21,9 @@ func ValidateNetworkTopologySnapshotRequest(request NetworkTopologySnapshotReque
 			return fmt.Errorf("unknown or duplicate topology source query")
 		}
 		seen[query] = true
+		if query.Name != "" && (definition.RequiresCustomResourceAccess() || len(query.Name) > 253 || !topologyNamePattern.MatchString(query.Name) || definition.Namespaced && query.Namespace == "") {
+			return fmt.Errorf("invalid named topology query")
+		}
 		if query.Namespace != "" && (!definition.Namespaced || len(query.Namespace) > 63 || !topologyNamespacePattern.MatchString(query.Namespace)) {
 			return fmt.Errorf("invalid topology source namespace")
 		}

package/resource/observed_workload.go

@@ -0,0 +1,18 @@
+package resource
+
+import "regexp"
+
+var workloadUIDPattern = regexp.MustCompile(`^[A-Za-z0-9._-]{1,128}$`)
+
+// ValidWorkloadUID validates an observed Kubernetes UID at the API boundary.
+func ValidWorkloadUID(uid string) bool {
+	return workloadUIDPattern.MatchString(uid)
+}
+
+// ObservedWorkloadDeleteRequest is the Agent request for UID-guarded workload deletion.
+type ObservedWorkloadDeleteRequest struct {
+	Namespace   string `json:"namespace"`
+	Kind        string `json:"kind"`
+	Name        string `json:"name"`
+	ExpectedUID string `json:"expectedUid"`
+}

package/resource/pod_execution.go

@@ -0,0 +1,206 @@
+package resource
+
+import (
+	"encoding/base64"
+	"fmt"
+	"strings"
+	"time"
+	"unicode"
+	"unicode/utf8"
+
+	"k8s.io/apimachinery/pkg/util/validation"
+)
+
+const (
+	PodExecutionProtocolVersion        = "1"
+	PodExecDefaultTimeoutSeconds int64 = 10
+	PodExecMaxTimeoutSeconds     int64 = 300
+	PodExecDefaultOutputBytes    int64 = 64 << 10
+	PodArgvMaxOutputBytes        int64 = 1 << 20
+	PodExecMaxStdinBytes               = 64 << 10
+)
+
+// PodArgvInput never adds a shell. A caller may explicitly select a shell in
+// argv, under the same exec authorization and immutable execution receipt.
+type PodArgvInput struct {
+	ExpectedUID    string   `json:"expectedUid"`
+	Container      string   `json:"container,omitempty"`
+	Argv           []string `json:"argv"`
+	StdinBase64    string   `json:"stdinBase64,omitempty"`
+	TimeoutSeconds int64    `json:"timeoutSeconds,omitempty"`
+	MaxOutputBytes int64    `json:"maxOutputBytes,omitempty"`
+}
+
+func (input PodArgvInput) Normalized() (PodArgvInput, error) {
+	if input.ExpectedUID == "" || len(input.ExpectedUID) > 256 || strings.IndexFunc(input.ExpectedUID, func(r rune) bool { return unicode.IsSpace(r) || unicode.IsControl(r) }) >= 0 {
+		return PodArgvInput{}, fmt.Errorf("a reviewed Pod UID of at most 256 bytes without whitespace or controls is required")
+	}
+	if input.Container != "" && len(validation.IsDNS1123Label(input.Container)) > 0 {
+		return PodArgvInput{}, fmt.Errorf("container must be one valid Kubernetes container name")
+	}
+	if len(input.Argv) < 1 || len(input.Argv) > 64 || strings.TrimSpace(input.Argv[0]) == "" {
+		return PodArgvInput{}, fmt.Errorf("argv requires one executable and at most 64 arguments")
+	}
+	total := 0
+	for _, arg := range input.Argv {
+		if len(arg) > 8192 || strings.ContainsRune(arg, 0) {
+			return PodArgvInput{}, fmt.Errorf("argv values must be bounded and contain no NUL")
+		}
+		total += len(arg)
+		if total > 32768 {
+			return PodArgvInput{}, fmt.Errorf("argv exceeds the 32768 byte budget")
+		}
+	}
+	if input.TimeoutSeconds < 0 || input.TimeoutSeconds > PodExecMaxTimeoutSeconds || input.MaxOutputBytes < 0 || input.MaxOutputBytes > PodArgvMaxOutputBytes {
+		return PodArgvInput{}, fmt.Errorf("exec timeout or combined output budget is outside the supported bounds")
+	}
+	if input.TimeoutSeconds == 0 {
+		input.TimeoutSeconds = PodExecDefaultTimeoutSeconds
+	}
+	if input.MaxOutputBytes == 0 {
+		input.MaxOutputBytes = PodExecDefaultOutputBytes
+	}
+	if len(input.StdinBase64) > base64.StdEncoding.EncodedLen(PodExecMaxStdinBytes) {
+		return PodArgvInput{}, fmt.Errorf("stdin exceeds the 65536 byte budget")
+	}
+	stdin, err := base64.StdEncoding.Strict().DecodeString(input.StdinBase64)
+	if err != nil || len(stdin) > PodExecMaxStdinBytes || base64.StdEncoding.EncodeToString(stdin) != input.StdinBase64 {
+		return PodArgvInput{}, fmt.Errorf("stdin must be bounded standard base64")
+	}
+	input.StdinBase64 = base64.StdEncoding.EncodeToString(stdin)
+	input.Argv = append([]string(nil), input.Argv...)
+	return input, nil
+}
+
+type PodExecutionOutput struct {
+	Status                 string `json:"status"`
+	ExitCode               *int64 `json:"exitCode,omitempty"`
+	Stdout                 string `json:"stdout"`
+	Stderr                 string `json:"stderr"`
+	StdoutEncoding         string `json:"stdoutEncoding"`
+	StderrEncoding         string `json:"stderrEncoding"`
+	StdoutBytes            int64  `json:"stdoutBytes"`
+	StderrBytes            int64  `json:"stderrBytes"`
+	MaxOutputBytes         int64  `json:"maxOutputBytes"`
+	StdoutTruncated        bool   `json:"stdoutTruncated"`
+	StderrTruncated        bool   `json:"stderrTruncated"`
+	UIDVerifiedBeforeStart bool   `json:"uidVerifiedBeforeStart"`
+	TargetChanged          bool   `json:"targetChanged"`
+	ReasonCode             string `json:"reasonCode,omitempty"`
+}
+
+func DecodePodExecutionStream(value, encoding string) ([]byte, error) {
+	switch encoding {
+	case "utf-8":
+		if len(value) > int(PodArgvMaxOutputBytes) || !utf8.ValidString(value) {
+			return nil, fmt.Errorf("invalid or oversized UTF-8 process output")
+		}
+		return []byte(value), nil
+	case "base64":
+		if len(value) > base64.StdEncoding.EncodedLen(int(PodArgvMaxOutputBytes)) {
+			return nil, fmt.Errorf("oversized process output")
+		}
+		data, err := base64.StdEncoding.Strict().DecodeString(value)
+		if err != nil || int64(len(data)) > PodArgvMaxOutputBytes || base64.StdEncoding.EncodeToString(data) != value {
+			return nil, fmt.Errorf("invalid base64 process output")
+		}
+		return data, nil
+	default:
+		return nil, fmt.Errorf("unsupported process output encoding")
+	}
+}
+
+type PodExecutionTarget struct {
+	Namespace string    `json:"namespace"`
+	PodName   string    `json:"podName"`
+	UID       string    `json:"uid"`
+	Container string    `json:"container"`
+	CheckedAt time.Time `json:"checkedAt"`
+}
+
+type PodArgvResult struct {
+	Target PodExecutionTarget `json:"target"`
+	Output PodExecutionOutput `json:"output"`
+}
+
+// Validate rejects a response from a mismatched or incompatible execution
+// adapter before its data can enter a durable receipt.
+func (result PodArgvResult) Validate(namespace, name string, input PodArgvInput) error {
+	target, output := result.Target, result.Output
+	if target.Namespace != namespace || target.PodName != name || target.UID != input.ExpectedUID || target.CheckedAt.IsZero() || len(validation.IsDNS1123Label(target.Container)) > 0 || input.Container != "" && target.Container != input.Container {
+		return fmt.Errorf("pod execution response target does not match")
+	}
+	if err := output.Validate(input.MaxOutputBytes); err != nil {
+		return err
+	}
+	return nil
+}
+
+func (output PodExecutionOutput) Validate(maximum int64) error {
+	if maximum < 1 || maximum > PodArgvMaxOutputBytes || output.MaxOutputBytes != maximum || !output.UIDVerifiedBeforeStart || output.TargetChanged && output.Status != "unknown" {
+		return fmt.Errorf("invalid Pod execution output bounds or identity")
+	}
+	switch output.Status {
+	case "succeeded":
+		if output.ExitCode == nil || *output.ExitCode != 0 {
+			return fmt.Errorf("successful Pod execution requires exit code zero")
+		}
+	case "failed":
+		if output.ExitCode == nil {
+			return fmt.Errorf("failed process requires a known exit code")
+		}
+	case "timed_out", "canceled", "transport_lost", "unknown":
+	default:
+		return fmt.Errorf("invalid Pod execution status")
+	}
+	if output.ExitCode != nil && (*output.ExitCode < 0 || *output.ExitCode > 4294967295) {
+		return fmt.Errorf("invalid process exit code")
+	}
+	stdout, err := DecodePodExecutionStream(output.Stdout, output.StdoutEncoding)
+	if err != nil {
+		return err
+	}
+	stderr, err := DecodePodExecutionStream(output.Stderr, output.StderrEncoding)
+	if err != nil {
+		return err
+	}
+	if int64(len(stdout)+len(stderr)) > maximum || !validPodStreamCount(output.StdoutBytes, len(stdout), output.StdoutTruncated) || !validPodStreamCount(output.StderrBytes, len(stderr), output.StderrTruncated) {
+		return fmt.Errorf("inconsistent Pod execution output counters")
+	}
+	return nil
+}
+
+func validPodStreamCount(observed int64, retained int, truncated bool) bool {
+	if truncated {
+		return observed > int64(retained)
+	}
+	return observed == int64(retained)
+}
+
+type PodExecutionReceipt struct {
+	ID              string              `json:"id"`
+	Status          string              `json:"status"`
+	ClusterID       string              `json:"clusterId"`
+	Namespace       string              `json:"namespace"`
+	PodName         string              `json:"podName"`
+	ExpectedUID     string              `json:"expectedUid"`
+	Container       string              `json:"container"`
+	CreatedAt       time.Time           `json:"createdAt"`
+	DeadlineAt      time.Time           `json:"deadlineAt"`
+	ExpiresAt       time.Time           `json:"expiresAt"`
+	FinishedAt      *time.Time          `json:"finishedAt,omitempty"`
+	OutputAvailable bool                `json:"outputAvailable"`
+	Output          *PodExecutionOutput `json:"output,omitempty"`
+}
+
+type AgentPodExecutionCapabilities struct {
+	TerminalVersion        string `json:"terminalVersion,omitempty"`
+	MaxSessionSeconds      int64  `json:"maxSessionSeconds,omitempty"`
+	MaxTerminalInputBytes  int64  `json:"maxTerminalInputBytes,omitempty"`
+	MaxTerminalOutputBytes int64  `json:"maxTerminalOutputBytes,omitempty"`
+	ProtocolVersion        string `json:"protocolVersion"`
+	ArgvVersion            string `json:"argvVersion"`
+	Ready                  bool   `json:"ready"`
+	MaxTimeoutSeconds      int64  `json:"maxTimeoutSeconds"`
+	MaxOutputBytes         int64  `json:"maxOutputBytes"`
+}

package/resource/pod_execution_gateway.go

@@ -0,0 +1,119 @@
+package resource
+
+import (
+	"fmt"
+	"regexp"
+	"time"
+	"unicode"
+	"unicode/utf8"
+
+	"k8s.io/apimachinery/pkg/util/validation"
+)
+
+// PodArgvToolInput mirrors the closed KubernetesPodArgvToolInput schema.
+// Gateway-only schemas are not HTTP operations and are pruned by the Go HTTP
+// generator. These helpers share the existing runtime's semantic validation;
+// they neither authorize a caller nor start a process.
+type PodArgvToolInput struct {
+	ClusterID      string       `json:"clusterId"`
+	Namespace      string       `json:"namespace"`
+	PodName        string       `json:"podName"`
+	IdempotencyKey string       `json:"idempotencyKey"`
+	Execution      PodArgvInput `json:"execution"`
+}
+
+func (input PodArgvToolInput) Normalized() (PodArgvToolInput, error) {
+	if !validPodToolTarget(input.ClusterID, input.Namespace, input.PodName) || !validPodToolKey(input.IdempotencyKey) {
+		return PodArgvToolInput{}, fmt.Errorf("valid cluster, namespace, Pod and original execution key are required")
+	}
+	execution, err := input.Execution.Normalized()
+	if err != nil {
+		return PodArgvToolInput{}, err
+	}
+	input.Execution = execution
+	return input, nil
+}
+
+type PodExecutionLookupInput struct {
+	ClusterID      string `json:"clusterId"`
+	Namespace      string `json:"namespace"`
+	PodName        string `json:"podName"`
+	ExecutionID    string `json:"executionId,omitempty"`
+	IdempotencyKey string `json:"idempotencyKey,omitempty"`
+}
+
+// PodGatewayResult is a safe Gateway projection, not the raw native receipt.
+// Receipt never carries Output and always has OutputAvailable=false. Text
+// output may be redacted; its byte counters retain original source counts.
+// Binary output must be withheld instead of forwarding encoded secret bytes.
+type PodGatewayResult struct {
+	Receipt     PodGatewayReceipt   `json:"receipt"`
+	OutputState string              `json:"outputState"`
+	Output      *PodExecutionOutput `json:"output,omitempty"`
+}
+
+// PodGatewayReceipt cannot hold raw process streams. Construct Gateway results
+// through NewPodGatewayResult; its outputAvailable flag is always false.
+type PodGatewayReceipt struct {
+	ID              string     `json:"id"`
+	Status          string     `json:"status"`
+	ClusterID       string     `json:"clusterId"`
+	Namespace       string     `json:"namespace"`
+	PodName         string     `json:"podName"`
+	ExpectedUID     string     `json:"expectedUid"`
+	Container       string     `json:"container"`
+	CreatedAt       time.Time  `json:"createdAt"`
+	DeadlineAt      time.Time  `json:"deadlineAt"`
+	ExpiresAt       time.Time  `json:"expiresAt"`
+	FinishedAt      *time.Time `json:"finishedAt,omitempty"`
+	OutputAvailable bool       `json:"outputAvailable"`
+}
+
+func NewPodGatewayResult(receipt PodExecutionReceipt) PodGatewayResult {
+	return PodGatewayResult{OutputState: "unavailable", Receipt: PodGatewayReceipt{
+		ID: receipt.ID, Status: receipt.Status, ClusterID: receipt.ClusterID,
+		Namespace: receipt.Namespace, PodName: receipt.PodName,
+		ExpectedUID: receipt.ExpectedUID, Container: receipt.Container,
+		CreatedAt: receipt.CreatedAt, DeadlineAt: receipt.DeadlineAt,
+		ExpiresAt: receipt.ExpiresAt, FinishedAt: receipt.FinishedAt,
+	}}
+}
+
+var podToolExecutionID = regexp.MustCompile(`^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$`)
+
+func (input PodExecutionLookupInput) Validate() error {
+	if !validPodToolTarget(input.ClusterID, input.Namespace, input.PodName) {
+		return fmt.Errorf("valid cluster, namespace and Pod are required")
+	}
+	if (input.ExecutionID == "") == (input.IdempotencyKey == "") {
+		return fmt.Errorf("exactly one original execution ID or key is required")
+	}
+	if input.ExecutionID != "" && !podToolExecutionID.MatchString(input.ExecutionID) || input.IdempotencyKey != "" && !validPodToolKey(input.IdempotencyKey) {
+		return fmt.Errorf("invalid original execution ID or key")
+	}
+	return nil
+}
+
+func validPodToolTarget(cluster, namespace, pod string) bool {
+	if cluster == "" || !utf8.ValidString(cluster) || utf8.RuneCountInString(cluster) > 256 {
+		return false
+	}
+	for _, char := range cluster {
+		if unicode.IsControl(char) || unicode.IsSpace(char) || char == '\ufeff' {
+			return false
+		}
+	}
+	return len(validation.IsDNS1123Label(namespace)) == 0 && len(validation.IsDNS1123Subdomain(pod)) == 0
+}
+
+func validPodToolKey(key string) bool {
+	if len(key) < 1 || len(key) > 128 {
+		return false
+	}
+	for _, char := range key {
+		if char < '!' || char > '~' {
+			return false
+		}
+	}
+	return true
+}