@opensoha/contracts 0.1.24 → 0.1.26

package/resource/network_topology_projection.go

@@ -0,0 +1,208 @@
+package resource
+
+import (
+	"encoding/json"
+	"fmt"
+	"sort"
+	"strings"
+)
+
+// ProjectNetworkTopologyObject is the wire allowlist shared by both Kubernetes readers.
+// Wildcards copy scalar label values only; no arbitrary manifest subtree is transported.
+func ProjectNetworkTopologyObject(source string, object map[string]any) (map[string]any, error) {
+	paths, ok := topologyProjectionPaths[source]
+	if !ok {
+		return nil, fmt.Errorf("unknown topology source")
+	}
+	paths = append(strings.Fields("metadata.name metadata.namespace metadata.uid metadata.resourceVersion metadata.generation"), paths...)
+	tree := map[string]any{}
+	for _, path := range paths {
+		addTopologyProjectionPath(tree, strings.Split(path, "."))
+	}
+	projected, _ := projectTopologyValue(object, tree).(map[string]any)
+	redactTopologyMatches(projected, "")
+	if source == "kubernetes.endpointslices" {
+		if metadata, ok := projected["metadata"].(map[string]any); ok {
+			if labels, ok := metadata["labels"].(map[string]any); ok {
+				metadata["labels"] = map[string]any{"kubernetes.io/service-name": labels["kubernetes.io/service-name"]}
+			}
+		}
+	}
+	if source == "traefik.middlewares" || source == "traefik.middlewaretcps" {
+		projected["processorTypes"] = topologyMiddlewareTypes(object)
+	}
+	raw, err := json.Marshal(projected)
+	if err != nil || len(raw) > NetworkTopologyMaxObjectBytes {
+		return nil, fmt.Errorf("topology object exceeds projection budget")
+	}
+	return projected, nil
+}
+
+func addTopologyProjectionPath(tree map[string]any, path []string) {
+	if len(path) == 0 {
+		return
+	}
+	if len(path) == 1 {
+		tree[path[0]] = true
+		return
+	}
+	next, _ := tree[path[0]].(map[string]any)
+	if next == nil {
+		next = map[string]any{}
+		tree[path[0]] = next
+	}
+	addTopologyProjectionPath(next, path[1:])
+}
+
+func projectTopologyValue(value any, tree map[string]any) any {
+	switch input := value.(type) {
+	case map[string]any:
+		output := map[string]any{}
+		for key, value := range input {
+			rule, ok := tree[key]
+			if !ok {
+				rule, ok = tree["*"]
+			}
+			if !ok {
+				continue
+			}
+			if children, ok := rule.(map[string]any); ok {
+				output[key] = projectTopologyValue(value, children)
+			} else if safe, ok := topologyLeaf(value); ok {
+				output[key] = safe
+			}
+		}
+		return output
+	case []any:
+		output := make([]any, 0, len(input))
+		for _, value := range input {
+			if scalarTopologyValue(value) {
+				output = append(output, value)
+			} else {
+				output = append(output, projectTopologyValue(value, tree))
+			}
+		}
+		return output
+	default:
+		if scalarTopologyValue(value) {
+			return value
+		}
+		return nil
+	}
+}
+
+func scalarTopologyValue(value any) bool {
+	switch value.(type) {
+	case nil, string, bool, float64, json.Number, int, int32, int64:
+		return true
+	}
+	return false
+}
+
+func redactTopologyMatches(value any, key string) {
+	switch item := value.(type) {
+	case map[string]any:
+		if key == "headers" || key == "queryParams" || key == "exprs" {
+			if _, ok := item["value"]; ok {
+				item["value"] = "[redacted]"
+			}
+			if _, ok := item["set"]; ok {
+				item["set"] = []any{"[redacted]"}
+			}
+		}
+		if match, ok := item["match"].(string); ok && (strings.Contains(strings.ToLower(match), "header") || strings.Contains(strings.ToLower(match), "query")) {
+			item["match"] = "[redacted match expression]"
+		}
+		for child, value := range item {
+			redactTopologyMatches(value, child)
+		}
+	case []any:
+		for _, value := range item {
+			redactTopologyMatches(value, key)
+		}
+	}
+}
+
+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"),
+}
+
+func gatewayTopologyPaths() []string {
+	return strings.Fields("spec.hostnames spec.parentRefs.group spec.parentRefs.kind spec.parentRefs.name spec.parentRefs.namespace spec.parentRefs.sectionName spec.parentRefs.port spec.rules.name spec.rules.matches.path.type spec.rules.matches.path.value spec.rules.matches.method spec.rules.matches.method.type spec.rules.matches.method.service spec.rules.matches.method.method spec.rules.matches.headers.name spec.rules.matches.headers.type spec.rules.matches.headers.value spec.rules.matches.queryParams.name spec.rules.matches.queryParams.type spec.rules.matches.queryParams.value spec.rules.backendRefs.group spec.rules.backendRefs.kind spec.rules.backendRefs.name spec.rules.backendRefs.namespace spec.rules.backendRefs.port spec.rules.backendRefs.weight spec.rules.filters.type spec.rules.filters.requestMirror.backendRef.group spec.rules.filters.requestMirror.backendRef.kind spec.rules.filters.requestMirror.backendRef.name spec.rules.filters.requestMirror.backendRef.namespace spec.rules.filters.requestMirror.backendRef.port spec.rules.filters.requestMirror.percent status.parents.parentRef.name status.parents.parentRef.namespace status.parents.parentRef.sectionName status.parents.conditions.type status.parents.conditions.status status.parents.conditions.reason status.parents.conditions.observedGeneration status.parents.conditions.lastTransitionTime")
+}
+func gatewayL4TopologyPaths() []string {
+	return strings.Fields("spec.hostnames spec.parentRefs.group spec.parentRefs.kind spec.parentRefs.name spec.parentRefs.namespace spec.parentRefs.sectionName spec.parentRefs.port spec.rules.name spec.rules.backendRefs.group spec.rules.backendRefs.kind spec.rules.backendRefs.name spec.rules.backendRefs.namespace spec.rules.backendRefs.port spec.rules.backendRefs.weight status.parents.parentRef.name status.parents.parentRef.namespace status.parents.parentRef.sectionName status.parents.conditions.type status.parents.conditions.status status.parents.conditions.reason status.parents.conditions.observedGeneration status.parents.conditions.lastTransitionTime")
+}
+func traefikTopologyPaths() []string {
+	return strings.Fields("spec.entryPoints spec.tls.passthrough spec.routes.kind spec.routes.match spec.routes.priority spec.routes.middlewares.name spec.routes.middlewares.namespace spec.routes.services.name spec.routes.services.namespace spec.routes.services.kind spec.routes.services.port spec.routes.services.weight spec.routes.services.scheme")
+}
+func apisixTopologyPaths() []string {
+	return strings.Fields("spec.ingressClassName spec.http.name spec.http.priority spec.http.match.hosts spec.http.match.paths spec.http.match.methods spec.http.match.remoteAddrs spec.http.match.exprs.subject.scope spec.http.match.exprs.subject.name spec.http.match.exprs.op spec.http.match.exprs.value spec.http.match.exprs.set spec.http.backend.serviceName spec.http.backend.servicePort spec.http.backend.weight spec.http.backends.serviceName spec.http.backends.servicePort spec.http.backends.weight spec.http.plugins.name spec.http.plugins.enable spec.stream.name spec.stream.protocol spec.stream.match.ingressPort spec.stream.backend.serviceName spec.stream.backend.servicePort spec.stream.backend.weight")
+}
+
+func topologyLeaf(value any) (any, bool) {
+	if scalarTopologyValue(value) {
+		return value, true
+	}
+	if items, ok := value.([]any); ok {
+		output := []any{}
+		for _, item := range items {
+			if !scalarTopologyValue(item) {
+				return nil, false
+			}
+			output = append(output, item)
+		}
+		return output, true
+	}
+	return nil, false
+}
+
+func topologyMiddlewareTypes(input map[string]any) []string {
+	allowed := strings.Fields("addPrefix basicAuth buffer circuitBreaker chain compress contentType digestAuth errors forwardAuth grpcWeb headers inFlightReq ipAllowList ipWhiteList passTLSClientCert rateLimit redirectRegex redirectScheme replacePath replacePathRegex retry stripPrefix stripPrefixRegex inFlightConn ipAllowListTCP")
+	found := map[string]bool{}
+	if spec, ok := input["spec"].(map[string]any); ok {
+		for key := range spec {
+			for _, name := range allowed {
+				if key == name {
+					found[name] = true
+				}
+			}
+		}
+	}
+	if existing, ok := input["processorTypes"].([]any); ok {
+		for _, value := range existing {
+			for _, name := range allowed {
+				if value == name {
+					found[name] = true
+				}
+			}
+		}
+	}
+	result := []string{}
+	for name := range found {
+		result = append(result, name)
+	}
+	sort.Strings(result)
+	return result
+}

package/resource/network_topology_projection_test.go

@@ -0,0 +1,53 @@
+package resource
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+func TestTopologyProjectionExcludesCredentialsAndPreservesAlternatives(t *testing.T) {
+	for _, test := range []struct {
+		source, input string
+		keep          []string
+	}{
+		{"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"}},
+		{"gateway.tlsroutes", `{"spec":{"hostnames":["secure.test"],"parentRefs":[{"name":"gw","sectionName":"tls"}],"rules":[{"backendRefs":[{"name":"web","port":9443}]}],"tls":{"key":"secret-value"}}}`, []string{"secure.test", "tls", "9443"}},
+		{"gateway.udproutes", `{"spec":{"parentRefs":[{"name":"gw","sectionName":"udp"}],"rules":[{"backendRefs":[{"name":"dns","port":53,"weight":2}]}]},"status":{"parents":[{"conditions":[{"type":"Accepted","status":"True","message":"secret-value"}]}]}}`, []string{"udp", "53", "Accepted"}},
+		{"apisix.apisixroutes", `{"metadata":{"name":"r"},"spec":{"http":[{"match":{"hosts":["a.test","b.test"],"paths":["/a","/b"],"exprs":[{"subject":{"scope":"Header","name":"token"},"value":"secret-value"}]},"plugins":[{"name":"key-auth","enable":true,"config":{"key":"secret-value"},"secretRef":"secret-value"}]}]}}`, []string{"a.test", "b.test", "/a", "/b", "key-auth"}},
+		{"traefik.ingressroutes", `{"metadata":{"name":"r"},"spec":{"routes":[{"match":"Header(authorization,secret-value)","services":[{"name":"web","port":80}]}],"tls":{"secretName":"secret-value"}}}`, []string{"[redacted match expression]", "web"}},
+		{"traefik.middlewares", `{"metadata":{"name":"m"},"spec":{"basicAuth":{"users":["secret-value"]},"chain":{"middlewares":[{"name":"next"}]}}}`, []string{"basicAuth", "next"}},
+	} {
+		t.Run(test.source, func(t *testing.T) {
+			var raw map[string]any
+			if err := json.Unmarshal([]byte(test.input), &raw); err != nil {
+				t.Fatal(err)
+			}
+			projection, err := ProjectNetworkTopologyObject(test.source, raw)
+			if err != nil {
+				t.Fatal(err)
+			}
+			data, _ := json.Marshal(projection)
+			if strings.Contains(string(data), "secret-value") {
+				t.Fatalf("credential escaped: %s", data)
+			}
+			for _, value := range test.keep {
+				if !strings.Contains(string(data), value) {
+					t.Fatalf("lost %q: %s", value, data)
+				}
+			}
+			var again map[string]any
+			_ = json.Unmarshal(data, &again)
+			second, err := ProjectNetworkTopologyObject(test.source, again)
+			if err != nil {
+				t.Fatal(err)
+			}
+			data2, _ := json.Marshal(second)
+			if string(data) != string(data2) {
+				t.Fatalf("projection is not stable: %s -> %s", data, data2)
+			}
+		})
+	}
+}

package/resource/network_topology_test.go

@@ -0,0 +1,51 @@
+package resource
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestTopologySourceQueriesCannotSelectArbitraryResourcesOrEscapeScope(t *testing.T) {
+	valid := NetworkTopologySnapshotRequest{Queries: []NetworkTopologySourceQuery{{SourceID: "traefik.ingressroutes", Namespace: "team-a"}, {SourceID: "kubernetes.ingressclasses"}}}
+	if err := ValidateNetworkTopologySnapshotRequest(valid); err != nil {
+		t.Fatal(err)
+	}
+	for _, queries := range [][]NetworkTopologySourceQuery{
+		nil,
+		{{SourceID: "kubernetes.secrets", Namespace: "team-a"}},
+		{{SourceID: "traefik.ingressroutes", Namespace: "../../secrets"}},
+		{{SourceID: "kubernetes.ingressclasses", Namespace: "team-a"}},
+		{{SourceID: "traefik.ingressroutes", Namespace: strings.Repeat("a", 64)}},
+		{{SourceID: "traefik.ingressroutes"}, {SourceID: "traefik.ingressroutes"}},
+		make([]NetworkTopologySourceQuery, NetworkTopologyMaxQueries+1),
+	} {
+		if err := ValidateNetworkTopologySnapshotRequest(NetworkTopologySnapshotRequest{Queries: queries}); err == nil {
+			t.Fatalf("unsafe snapshot queries accepted: %+v", queries)
+		}
+	}
+}
+
+func TestTopologySourcesKeepSupportedVersionsAndDedicatedKindsExplicit(t *testing.T) {
+	seen := map[string]bool{}
+	for _, definition := range NetworkTopologySources() {
+		if seen[definition.ID] || definition.Kind == "Secret" || definition.Resource == "secrets" || definition.Resource == "*" || definition.Group == "*" {
+			t.Fatalf("unsafe source registry: %+v", definition)
+		}
+		seen[definition.ID] = true
+	}
+	for _, id := range []string{"gateway.tcproutes", "gateway.tlsroutes", "gateway.udproutes"} {
+		d, ok := LookupNetworkTopologySource(id)
+		if !ok || d.Version != "v1" || d.FallbackVersion != "v1alpha2" || !d.RequiresCustomResourceAccess() {
+			t.Fatalf("Gateway L4 source must be versioned and explicitly authorized: %+v", d)
+		}
+	}
+	grant, ok := LookupNetworkTopologySource("gateway.referencegrants")
+	if !ok || grant.Version != "v1" || grant.FallbackVersion != "v1beta1" {
+		t.Fatalf("ReferenceGrant served-version support: %+v", grant)
+	}
+	definitions := NetworkTopologySources()
+	definitions[0].Kind = "Secret"
+	if NetworkTopologySources()[0].Kind == "Secret" {
+		t.Fatal("source allowlist is mutable by callers")
+	}
+}

package/resource/network_topology_validation.go

@@ -0,0 +1,29 @@
+package resource
+
+import (
+	"errors"
+	"fmt"
+	"regexp"
+)
+
+var topologyNamespacePattern = regexp.MustCompile(`^[a-z0-9]([a-z0-9-]*[a-z0-9])?$`)
+
+func ValidateNetworkTopologySnapshotRequest(request NetworkTopologySnapshotRequest) error {
+	if len(request.Queries) == 0 || len(request.Queries) > NetworkTopologyMaxQueries {
+		return fmt.Errorf("topology snapshot requires between 1 and 64 source queries")
+	}
+	seen := make(map[NetworkTopologySourceQuery]bool, len(request.Queries))
+	for _, query := range request.Queries {
+		definition, ok := LookupNetworkTopologySource(query.SourceID)
+		if !ok || seen[query] {
+			return fmt.Errorf("unknown or duplicate topology source query")
+		}
+		seen[query] = true
+		if query.Namespace != "" && (!definition.Namespaced || len(query.Namespace) > 63 || !topologyNamespacePattern.MatchString(query.Namespace)) {
+			return fmt.Errorf("invalid topology source namespace")
+		}
+	}
+	return nil
+}
+
+var ErrNetworkTopologySnapshotUnsupported = errors.New("agent topology snapshot unsupported")

package/resource/node_drain.go

@@ -0,0 +1,34 @@
+package resource
+
+// NodeDrainError reports an incomplete drain without exposing provider error text.
+type NodeDrainError struct {
+	Code  string
+	Cause error
+}
+
+func (e *NodeDrainError) Error() string {
+	switch e.Code {
+	case "node_drain_pdb_blocked":
+		return "PodDisruptionBudget blocked eviction. The drain did not complete; inspect remaining pods and scheduling before retrying."
+	case "node_drain_eviction_blocked":
+		return "Eviction was repeatedly refused. Check disruption budgets or API throttling and inspect remaining pods before retrying."
+	case "node_drain_timeout":
+		return "The drain timed out before all evictable pods terminated. Inspect remaining pods and scheduling before retrying."
+	case "node_drain_canceled":
+		return "The drain was interrupted. Previously submitted evictions may still finish; inspect remaining pods and scheduling."
+	case "node_drain_pod_selection":
+		return "Evictable pods could not be selected. Check pod read access and drain options for unmanaged pods or emptyDir data."
+	default:
+		return "The drain did not complete. Inspect remaining pods, disruption budgets and permissions before retrying."
+	}
+}
+
+func (e *NodeDrainError) Unwrap() error { return e.Cause }
+
+func IsNodeDrainErrorCode(code string) bool {
+	switch code {
+	case "node_drain_pdb_blocked", "node_drain_eviction_blocked", "node_drain_timeout", "node_drain_canceled", "node_drain_pod_selection", "node_drain_failed":
+		return true
+	}
+	return false
+}

package/resource/relations.go

@@ -0,0 +1,225 @@
+package resource
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"regexp"
+	"strings"
+)
+
+const RelationSnapshotFeature = "resource-relations.metadata.v1"
+const RelationMaxQueries = 32
+const RelationMaxItems = 200
+const RelationMaxNodes = 500
+const RelationMaxDepth = 8
+
+var ErrRelationSnapshotUnsupported = errors.New("resource relation metadata snapshot unsupported")
+
+func DefaultRelationSources(namespace string) []RelationSource {
+	return []RelationSource{
+		{APIVersion: "v1", Resource: "pods", Kind: "Pod", Namespace: namespace},
+		{APIVersion: "apps/v1", Resource: "deployments", Kind: "Deployment", Namespace: namespace},
+		{APIVersion: "apps/v1", Resource: "replicasets", Kind: "ReplicaSet", Namespace: namespace},
+		{APIVersion: "apps/v1", Resource: "statefulsets", Kind: "StatefulSet", Namespace: namespace},
+		{APIVersion: "apps/v1", Resource: "daemonsets", Kind: "DaemonSet", Namespace: namespace},
+		{APIVersion: "batch/v1", Resource: "jobs", Kind: "Job", Namespace: namespace},
+		{APIVersion: "batch/v1", Resource: "cronjobs", Kind: "CronJob", Namespace: namespace},
+		{APIVersion: "v1", Resource: "services", Kind: "Service", Namespace: namespace},
+		{APIVersion: "v1", Resource: "persistentvolumeclaims", Kind: "PersistentVolumeClaim", Namespace: namespace},
+		{APIVersion: "v1", Resource: "configmaps", Kind: "ConfigMap", Namespace: namespace},
+		{APIVersion: "v1", Resource: "secrets", Kind: "Secret", Namespace: namespace},
+		{APIVersion: "networking.k8s.io/v1", Resource: "ingresses", Kind: "Ingress", Namespace: namespace},
+	}
+}
+
+func IsBuiltinRelationSource(source RelationSource) bool {
+	for _, builtin := range DefaultRelationSources(source.Namespace) {
+		if builtin == source {
+			return true
+		}
+	}
+	return false
+}
+
+// RelationSource always names an explicit namespaced API collection. Discovery
+// must verify the resource/kind pair before reading it.
+type RelationSource struct {
+	APIVersion string `json:"apiVersion"`
+	Resource   string `json:"resource"`
+	Kind       string `json:"kind"`
+	Namespace  string `json:"namespace"`
+}
+
+type RelationRule struct {
+	ID       string            `json:"id"`
+	Type     string            `json:"type"`
+	Target   RelationSource    `json:"target"`
+	Name     string            `json:"name,omitempty"`
+	UID      string            `json:"uid,omitempty"`
+	Selector map[string]string `json:"selector,omitempty"`
+}
+
+type RelationConfig struct {
+	Version string           `json:"version"`
+	RootUID string           `json:"rootUid"`
+	Sources []RelationSource `json:"sources"`
+	Rules   []RelationRule   `json:"rules"`
+}
+
+type RelationQuery struct {
+	ID       string            `json:"id"`
+	Source   RelationSource    `json:"source"`
+	Name     string            `json:"name,omitempty"`
+	Selector map[string]string `json:"selector,omitempty"`
+}
+
+type RelationSnapshotRequest struct {
+	Queries []RelationQuery `json:"queries"`
+}
+type RelationOwner struct {
+	APIVersion string `json:"apiVersion"`
+	Kind       string `json:"kind"`
+	Name       string `json:"name"`
+	UID        string `json:"uid"`
+	Controller bool   `json:"controller"`
+}
+
+type RelationObject struct {
+	Resource ResourceRef     `json:"resource"`
+	Owners   []RelationOwner `json:"owners,omitempty"`
+}
+type RelationCoverage struct {
+	QueryID    string `json:"queryId"`
+	State      string `json:"state"`
+	ReasonCode string `json:"reasonCode,omitempty"`
+	Truncated  bool   `json:"truncated"`
+}
+type RelationSourceResult struct {
+	Coverage RelationCoverage `json:"coverage"`
+	Objects  []RelationObject `json:"objects"`
+}
+type RelationSnapshot struct {
+	Version string                 `json:"version"`
+	Sources []RelationSourceResult `json:"sources"`
+}
+type RelationNode struct {
+	Resource ResourceRef `json:"resource"`
+	Role     string      `json:"role"`
+	Depth    int         `json:"depth"`
+}
+type RelationEdge struct {
+	FromUID string `json:"fromUid"`
+	ToUID   string `json:"toUid"`
+	Type    string `json:"type"`
+	RuleID  string `json:"ruleId,omitempty"`
+}
+type ResourceRelationsView struct {
+	Root       ResourceRef        `json:"root"`
+	Config     RelationConfig     `json:"config"`
+	Nodes      []RelationNode     `json:"nodes"`
+	Edges      []RelationEdge     `json:"edges"`
+	Coverage   []RelationCoverage `json:"coverage"`
+	Partial    bool               `json:"partial"`
+	ObservedAt string             `json:"observedAt"`
+}
+
+var relationDNS = regexp.MustCompile(`^[a-z0-9]([a-z0-9.-]*[a-z0-9])?$`)
+var relationKind = regexp.MustCompile(`^[A-Za-z][A-Za-z0-9]*$`)
+var relationToken = regexp.MustCompile(`^[a-zA-Z0-9_.-]+$`)
+var relationLabelKey = regexp.MustCompile(`^[a-zA-Z0-9_.-]+(/[a-zA-Z0-9_.-]+)?$`)
+
+func ValidateRelationSource(s RelationSource) error {
+	parts := strings.Split(s.APIVersion, "/")
+	if len(parts) > 2 || len(parts) == 0 || len(s.APIVersion) > 320 {
+		return fmt.Errorf("invalid resource API version")
+	}
+	for _, part := range parts {
+		if !relationDNS.MatchString(part) {
+			return fmt.Errorf("invalid resource API version")
+		}
+	}
+	if !relationDNS.MatchString(s.Resource) || len(s.Resource) > 63 || strings.Contains(s.Resource, ".") || !relationKind.MatchString(s.Kind) || len(s.Kind) > 128 {
+		return fmt.Errorf("invalid resource definition")
+	}
+	if !relationDNS.MatchString(s.Namespace) || strings.Contains(s.Namespace, ".") || len(s.Namespace) > 63 {
+		return fmt.Errorf("an explicit namespace is required")
+	}
+	return nil
+}
+
+func validateRelationSelector(selector map[string]string) error {
+	if len(selector) > 16 {
+		return fmt.Errorf("too many label terms")
+	}
+	for key, value := range selector {
+		if len(key) > 317 || !relationLabelKey.MatchString(key) || len(value) > 63 || (value != "" && !relationToken.MatchString(value)) {
+			return fmt.Errorf("invalid label selector")
+		}
+	}
+	return nil
+}
+
+func ValidateRelationConfig(config RelationConfig) error {
+	if config.Sources == nil || config.Rules == nil {
+		return fmt.Errorf("sources and rules must be arrays")
+	}
+	data, err := json.Marshal(config)
+	if err != nil || len(data) > 16<<10 || config.Version != "v1" || strings.TrimSpace(config.RootUID) == "" || len(config.RootUID) > 128 || len(config.Sources) > 8 || len(config.Rules) > 8 {
+		return fmt.Errorf("invalid relation configuration or budget")
+	}
+	for _, source := range config.Sources {
+		if err := ValidateRelationSource(source); err != nil {
+			return err
+		}
+	}
+	seen := map[string]bool{}
+	for _, rule := range config.Rules {
+		if !relationToken.MatchString(rule.ID) || len(rule.ID) > 64 || seen[rule.ID] {
+			return fmt.Errorf("invalid or duplicate rule ID")
+		}
+		seen[rule.ID] = true
+		if err := ValidateRelationSource(rule.Target); err != nil {
+			return err
+		}
+		switch rule.Type {
+		case "reference", "manual":
+			if !relationDNS.MatchString(rule.Name) || len(rule.Name) > 253 || len(rule.Selector) != 0 || len(rule.UID) > 128 || (rule.Type == "manual" && strings.TrimSpace(rule.UID) == "") {
+				return fmt.Errorf("named manual relations require a fixed UID")
+			}
+		case "selector":
+			if rule.Name != "" || rule.UID != "" || len(rule.Selector) == 0 {
+				return fmt.Errorf("selector rules must declare labels only")
+			}
+		default:
+			return fmt.Errorf("unknown relation rule type")
+		}
+		if err := validateRelationSelector(rule.Selector); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func ValidateRelationSnapshotRequest(input RelationSnapshotRequest) error {
+	if len(input.Queries) == 0 || len(input.Queries) > RelationMaxQueries {
+		return fmt.Errorf("invalid relation query budget")
+	}
+	seen := map[string]bool{}
+	for _, q := range input.Queries {
+		if q.ID == "" || len(q.ID) > 80 || !relationToken.MatchString(q.ID) || seen[q.ID] {
+			return fmt.Errorf("invalid query identity")
+		}
+		seen[q.ID] = true
+		if err := ValidateRelationSource(q.Source); err != nil {
+			return err
+		}
+		if q.Name != "" && (!relationDNS.MatchString(q.Name) || len(q.Name) > 253 || len(q.Selector) != 0) {
+			return fmt.Errorf("invalid named query")
+		}
+		if err := validateRelationSelector(q.Selector); err != nil {
+			return err
+		}
+	}
+	return nil
+}

package/resource/relations_test.go

@@ -0,0 +1,47 @@
+package resource
+
+import "testing"
+
+func TestRelationConfigSupportsUnknownKindsWithoutCodeRegistration(t *testing.T) {
+	source := RelationSource{APIVersion: "widgets.example.test/v1", Resource: "widgets", Kind: "Widget", Namespace: "team"}
+	config := RelationConfig{Version: "v1", RootUID: "root", Sources: []RelationSource{source}, Rules: []RelationRule{{ID: "shared", Type: "reference", Target: source, Name: "runtime"}}}
+	if err := ValidateRelationConfig(config); err != nil {
+		t.Fatal(err)
+	}
+	config.Rules[0].Type = "manual"
+	if ValidateRelationConfig(config) == nil {
+		t.Fatal("manual association accepted without UID")
+	}
+	config.Rules[0].UID = "fixed-runtime"
+	if err := ValidateRelationConfig(config); err != nil {
+		t.Fatal(err)
+	}
+	config.Rules[0].Target.Resource = "widgets/../../secrets"
+	if ValidateRelationConfig(config) == nil {
+		t.Fatal("path traversal accepted")
+	}
+}
+
+func TestRelationQueryBoundsAndSelectors(t *testing.T) {
+	q := RelationQuery{ID: "pods", Source: RelationSource{APIVersion: "v1", Resource: "pods", Kind: "Pod", Namespace: "team"}, Selector: map[string]string{"app": "demo"}}
+	for _, test := range []struct {
+		name   string
+		change func(*RelationQuery)
+	}{
+		{"all namespaces", func(q *RelationQuery) { q.Source.Namespace = "" }},
+		{"selector injection", func(q *RelationQuery) { q.Selector["app"] = "demo,secret=yes" }},
+		{"named selector", func(q *RelationQuery) { q.Name = "pod" }},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			copy := q
+			copy.Selector = map[string]string{"app": "demo"}
+			test.change(&copy)
+			if ValidateRelationSnapshotRequest(RelationSnapshotRequest{Queries: []RelationQuery{copy}}) == nil {
+				t.Fatal("invalid query accepted")
+			}
+		})
+	}
+	if ValidateRelationSnapshotRequest(RelationSnapshotRequest{Queries: []RelationQuery{q, q}}) == nil {
+		t.Fatal("duplicate query accepted")
+	}
+}