@opensoha/contracts 0.1.27 → 0.2.0

package/proxytransport/username.go

@@ -0,0 +1,51 @@
+package proxytransport
+
+import (
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"regexp"
+	"strings"
+)
+
+// MaxUsernameBytes bounds HTTP Basic usernames, including opaque mapped IDs.
+// Two maximum-length identifiers encode to fewer than 360 bytes.
+const MaxUsernameBytes = 512
+
+var mappedIdentifier = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$`)
+
+// EncodeMappedUsername encodes exactly [credentialID,nodeID] as canonical JSON
+// with unpadded URL-safe base64. Unlike the IDs, the result never contains ':',
+// which is reserved as HTTP Basic's username/password separator.
+func EncodeMappedUsername(credentialID, nodeID string) (string, error) {
+	if !mappedIdentifier.MatchString(credentialID) || !mappedIdentifier.MatchString(nodeID) {
+		return "", errors.New("invalid mapped proxy identifier")
+	}
+	data, err := json.Marshal([2]string{credentialID, nodeID})
+	if err != nil {
+		return "", err
+	}
+	return "v1." + base64.RawURLEncoding.EncodeToString(data), nil
+}
+
+// DecodeMappedUsername accepts only the canonical v1 encoding. It rejects
+// alternate JSON/base64 spellings so callers share one unambiguous identity key.
+func DecodeMappedUsername(username string) (credentialID, nodeID string, err error) {
+	invalid := errors.New("invalid mapped proxy username")
+	if len(username) > MaxUsernameBytes || !strings.HasPrefix(username, "v1.") {
+		return "", "", invalid
+	}
+	data, err := base64.RawURLEncoding.Strict().DecodeString(username[len("v1."):])
+	if err != nil {
+		return "", "", invalid
+	}
+	var identifiers []string
+	if json.Unmarshal(data, &identifiers) != nil || len(identifiers) != 2 {
+		return "", "", invalid
+	}
+	canonical, err := EncodeMappedUsername(identifiers[0], identifiers[1])
+	if err != nil || canonical != username {
+		return "", "", invalid
+	}
+	return identifiers[0], identifiers[1], nil
+}

package/proxytransport/username_test.go

@@ -0,0 +1,98 @@
+package proxytransport
+
+import (
+	"context"
+	"encoding/base64"
+	"net"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestMappedUsernameRoundTrip(t *testing.T) {
+	for _, ids := range [][2]string{{"c", "n"}, {"credential.a:b", "node:c.d"}, {"c" + strings.Repeat(":", 127), "n" + strings.Repeat(".", 127)}} {
+		username, err := EncodeMappedUsername(ids[0], ids[1])
+		if err != nil || strings.Contains(username, ":") || len(username) > MaxUsernameBytes {
+			t.Fatalf("encode: length=%d err=%v", len(username), err)
+		}
+		credentialID, nodeID, err := DecodeMappedUsername(username)
+		if err != nil || credentialID != ids[0] || nodeID != ids[1] {
+			t.Fatalf("round trip: %q %q %v", credentialID, nodeID, err)
+		}
+	}
+}
+
+func TestMappedUsernameRejectsInvalidEncodings(t *testing.T) {
+	encodedJSON := func(raw string) string { return "v1." + base64.RawURLEncoding.EncodeToString([]byte(raw)) }
+	canonical, err := EncodeMappedUsername("credential", "node")
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, tc := range []struct{ name, username string }{
+		{"unknown version", "v2." + strings.TrimPrefix(canonical, "v1.")},
+		{"oversized", strings.Repeat("a", MaxUsernameBytes+1)},
+		{"bad base64", "v1.!"},
+		{"empty payload", "v1."},
+		{"padded base64", canonical + "="},
+		{"base64 newline", canonical + "\n"},
+		{"not an array", encodedJSON(`{"credential":"node"}`)},
+		{"one item", encodedJSON(`["credential"]`)},
+		{"three items", encodedJSON(`["credential","node","extra"]`)},
+		{"nonstring item", encodedJSON(`["credential",1]`)},
+		{"null item", encodedJSON(`[null,"node"]`)},
+		{"invalid identifier", encodedJSON(`["credential","node/path"]`)},
+		{"trailing data", encodedJSON(`["credential","node"][]`)},
+		{"JSON whitespace", encodedJSON(`["credential", "node"]`)},
+		{"escaped spelling", encodedJSON(`["\u0063redential","node"]`)},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			if c, n, err := DecodeMappedUsername(tc.username); err == nil || c != "" || n != "" {
+				t.Fatalf("accepted noncanonical username: %q %q %v", c, n, err)
+			}
+		})
+	}
+	for _, id := range []string{"", ".leading", "contains space", "node/path", "节点", "a" + strings.Repeat("x", 128)} {
+		if _, err := EncodeMappedUsername(id, "node"); err == nil {
+			t.Fatalf("invalid identifier accepted: %q", id)
+		}
+		if _, err := EncodeMappedUsername("credential", id); err == nil {
+			t.Fatalf("invalid node identifier accepted: %q", id)
+		}
+	}
+}
+
+func TestMappedUsernameBasicAuthenticationAndLimit(t *testing.T) {
+	username, err := EncodeMappedUsername("c"+strings.Repeat(":", 127), "n"+strings.Repeat(".", 127))
+	if err != nil || len(username) <= 128 {
+		t.Fatalf("expected long encoded username: %d %v", len(username), err)
+	}
+	password := strings.Repeat("p", 32)
+	dial := func(context.Context, string, string) (net.Conn, error) { return nil, nil }
+	h, err := New(map[string]string{username: password}, dial, time.Now().Add(time.Minute))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = h.Close() }()
+	r := httptest.NewRequest("CONNECT", "http://example.invalid", nil)
+	r.SetBasicAuth(username, password)
+	r.Header.Set("Proxy-Authorization", r.Header.Get("Authorization"))
+	r.Header.Del("Authorization")
+	if got, ok := h.authenticate(r); !ok || got != username {
+		t.Fatal("mapped IDs containing colons failed Basic authentication")
+	}
+	r.SetBasicAuth(username, strings.Repeat("q", 32))
+	r.Header.Set("Proxy-Authorization", r.Header.Get("Authorization"))
+	if _, ok := h.authenticate(r); ok {
+		t.Fatal("wrong password accepted")
+	}
+	for _, size := range []int{MaxUsernameBytes, MaxUsernameBytes + 1} {
+		handler, err := New(map[string]string{strings.Repeat("u", size): password}, dial, time.Now().Add(time.Minute))
+		if size == MaxUsernameBytes && err != nil || size > MaxUsernameBytes && err == nil {
+			t.Fatalf("username size %d: %v", size, err)
+		}
+		if handler != nil {
+			_ = handler.Close()
+		}
+	}
+}

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/conditional_workload_action.go

@@ -0,0 +1,63 @@
+package resource
+
+import (
+	"fmt"
+	"strconv"
+)
+
+type ConditionalWorkloadActionInput struct {
+	Preconditions ResourceMutationPreconditions `json:"preconditions"`
+	Replicas      *int32                        `json:"replicas,omitempty"`
+	Revision      string                        `json:"revision,omitempty"`
+	DryRun        bool                          `json:"dryRun,omitempty"`
+}
+
+func (input ConditionalWorkloadActionInput) Validate(kind, action string) error {
+	if err := input.Preconditions.Validate(); err != nil {
+		return err
+	}
+	switch action {
+	case "restart":
+		if (kind != "Deployment" && kind != "StatefulSet" && kind != "DaemonSet") || input.Replicas != nil || input.Revision != "" {
+			return fmt.Errorf("restart supports Deployment, StatefulSet and DaemonSet without replicas or revision")
+		}
+	case "scale":
+		if (kind != "Deployment" && kind != "StatefulSet") || input.Replicas == nil || *input.Replicas < 0 || input.Revision != "" {
+			return fmt.Errorf("scale requires Deployment or StatefulSet and nonnegative replicas without revision")
+		}
+	case "rollback":
+		if kind != "Deployment" || input.Replicas != nil || !validWorkloadRevision(input.Revision) {
+			return fmt.Errorf("rollback requires Deployment and one positive revision without replicas")
+		}
+	default:
+		return fmt.Errorf("unsupported conditional workload action")
+	}
+	return nil
+}
+
+func validWorkloadRevision(value string) bool {
+	if value == "" || len(value) > 19 || value[0] == '0' {
+		return false
+	}
+	for _, r := range value {
+		if r < '0' || r > '9' {
+			return false
+		}
+	}
+	revision, err := strconv.ParseInt(value, 10, 64)
+	return err == nil && revision > 0
+}
+
+// The returned UID/version belongs to the API response. Applied acknowledges
+// an update, not observed rollout readiness. DryRun never changes live state.
+type ConditionalWorkloadActionReceipt struct {
+	Applied         bool                          `json:"applied"`
+	DryRun          bool                          `json:"dryRun"`
+	Kind            string                        `json:"kind"`
+	Name            string                        `json:"name"`
+	Namespace       string                        `json:"namespace"`
+	Action          string                        `json:"action"`
+	UID             string                        `json:"uid"`
+	ResourceVersion string                        `json:"resourceVersion"`
+	Preconditions   ResourceMutationPreconditions `json:"preconditions"`
+}

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"`
+}

package/resource/models.go

@@ -54,10 +54,17 @@ type ResourceGraphNode struct {
 }
 
 type ResourceGraphEdge struct {
-	ID       string `json:"id"`
-	SourceID string `json:"sourceId"`
-	TargetID string `json:"targetId"`
-	Relation string `json:"relation"`
+	ID              string       `json:"id"`
+	SourceID        string       `json:"sourceId"`
+	TargetID        string       `json:"targetId"`
+	Relation        string       `json:"relation"`
+	ResolutionState string       `json:"resolutionState,omitempty"`
+	Protocol        string       `json:"protocol,omitempty"`
+	Port            string       `json:"port,omitempty"`
+	SectionName     string       `json:"sectionName,omitempty"`
+	FieldPath       string       `json:"fieldPath,omitempty"`
+	Note            string       `json:"note,omitempty"`
+	SourceRef       *ResourceRef `json:"sourceRef,omitempty"`
 }
 
 type ResourceEvidence struct {
@@ -104,23 +111,34 @@ type NamespaceUpsertInput struct {
 }
 
 type PodView struct {
-	UID                    string               `json:"uid,omitempty"`
-	Name                   string               `json:"name"`
-	Namespace              string               `json:"namespace"`
-	Phase                  string               `json:"phase"`
-	NodeName               string               `json:"nodeName,omitempty"`
-	PodIP                  string               `json:"podIp,omitempty"`
-	CreatedAt              string               `json:"createdAt,omitempty"`
-	CPU                    string               `json:"cpu,omitempty"`
-	Memory                 string               `json:"memory,omitempty"`
-	Requests               ResourceQuantityView `json:"requests,omitempty"`
-	Limits                 ResourceQuantityView `json:"limits,omitempty"`
-	Labels                 map[string]string    `json:"labels,omitempty"`
-	PersistentVolumeClaims []string             `json:"persistentVolumeClaims,omitempty"`
-	ReadyContainers        string               `json:"readyContainers"`
-	Restarts               int32                `json:"restarts"`
-	AgeSeconds             int64                `json:"ageSeconds"`
-	AllowedActions         []string             `json:"allowedActions,omitempty"`
+	UID                    string                   `json:"uid,omitempty"`
+	Name                   string                   `json:"name"`
+	Namespace              string                   `json:"namespace"`
+	Phase                  string                   `json:"phase"`
+	NodeName               string                   `json:"nodeName,omitempty"`
+	PodIP                  string                   `json:"podIp,omitempty"`
+	CreatedAt              string                   `json:"createdAt,omitempty"`
+	CPU                    string                   `json:"cpu,omitempty"`
+	Memory                 string                   `json:"memory,omitempty"`
+	Requests               ResourceQuantityView     `json:"requests,omitempty"`
+	Limits                 ResourceQuantityView     `json:"limits,omitempty"`
+	Labels                 map[string]string        `json:"labels,omitempty"`
+	PersistentVolumeClaims []string                 `json:"persistentVolumeClaims,omitempty"`
+	ReadyContainers        string                   `json:"readyContainers"`
+	QOSClass               string                   `json:"qosClass,omitempty"`
+	ContainerStatuses      []PodContainerStatusView `json:"containerStatuses,omitempty"`
+	Restarts               int32                    `json:"restarts"`
+	AgeSeconds             int64                    `json:"ageSeconds"`
+	AllowedActions         []string                 `json:"allowedActions,omitempty"`
+}
+
+type PodContainerStatusView struct {
+	Name     string `json:"name"`
+	Kind     string `json:"kind"`
+	Ready    bool   `json:"ready"`
+	State    string `json:"state"`
+	Reason   string `json:"reason,omitempty"`
+	ExitCode *int32 `json:"exitCode,omitempty"`
 }
 
 type WorkloadOverviewNamespaceView struct {
@@ -340,10 +358,11 @@ type ResourceYAMLView struct {
 }
 
 type ResourceUpdatePlanRequest struct {
-	Namespace string `json:"namespace,omitempty"`
-	Kind      string `json:"kind"`
-	Name      string `json:"name"`
-	Content   string `json:"content"`
+	Namespace               string `json:"namespace,omitempty"`
+	Kind                    string `json:"kind"`
+	Name                    string `json:"name"`
+	Content                 string `json:"content"`
+	RequireObservedIdentity bool   `json:"requireObservedIdentity,omitempty"`
 }
 
 type ManagedFieldOwner struct {
@@ -434,6 +453,7 @@ type SubjectAccessReviewResult struct {
 type DeploymentView struct {
 	Name            string            `json:"name"`
 	Namespace       string            `json:"namespace"`
+	UID             string            `json:"uid,omitempty"`
 	Labels          map[string]string `json:"labels,omitempty"`
 	DesiredReplicas int32             `json:"desiredReplicas"`
 	ReadyReplicas   int32             `json:"readyReplicas"`
@@ -446,6 +466,7 @@ type DeploymentView struct {
 type DeploymentDetailView struct {
 	Name               string                  `json:"name"`
 	Namespace          string                  `json:"namespace"`
+	UID                string                  `json:"uid,omitempty"`
 	DesiredReplicas    int32                   `json:"desiredReplicas"`
 	ReadyReplicas      int32                   `json:"readyReplicas"`
 	UpdatedReplicas    int32                   `json:"updatedReplicas"`
@@ -464,13 +485,15 @@ type DeploymentDetailView struct {
 }
 
 type RolloutHistoryView struct {
-	Name          string   `json:"name"`
-	Namespace     string   `json:"namespace"`
-	Revision      string   `json:"revision"`
-	Images        []string `json:"images,omitempty"`
-	Replicas      int32    `json:"replicas"`
-	ReadyReplicas int32    `json:"readyReplicas"`
-	CreatedAt     string   `json:"createdAt,omitempty"`
+	Name                   string   `json:"name"`
+	Namespace              string   `json:"namespace"`
+	Revision               string   `json:"revision"`
+	Images                 []string `json:"images,omitempty"`
+	Replicas               int32    `json:"replicas"`
+	ReadyReplicas          int32    `json:"readyReplicas"`
+	CreatedAt              string   `json:"createdAt,omitempty"`
+	PodRevisionHash        string   `json:"podRevisionHash,omitempty"`
+	MatchesCurrentTemplate *bool    `json:"matchesCurrentTemplate,omitempty"`
 }
 
 type DeploymentRolloutStatusView struct {
@@ -556,34 +579,45 @@ type DaemonSetDetailView struct {
 }
 
 type JobView struct {
-	Name           string   `json:"name"`
-	Namespace      string   `json:"namespace"`
-	Completions    int32    `json:"completions"`
-	Succeeded      int32    `json:"succeeded"`
-	Failed         int32    `json:"failed"`
-	Active         int32    `json:"active"`
-	CompletionMode string   `json:"completionMode,omitempty"`
-	AgeSeconds     int64    `json:"ageSeconds"`
-	AllowedActions []string `json:"allowedActions,omitempty"`
+	Name             string                  `json:"name"`
+	Namespace        string                  `json:"namespace"`
+	Completions      int32                   `json:"completions"`
+	Succeeded        int32                   `json:"succeeded"`
+	Failed           int32                   `json:"failed"`
+	Active           int32                   `json:"active"`
+	CompletionMode   string                  `json:"completionMode,omitempty"`
+	AgeSeconds       int64                   `json:"ageSeconds"`
+	AllowedActions   []string                `json:"allowedActions,omitempty"`
+	CompletionTarget *int32                  `json:"completionTarget,omitempty"`
+	Suspend          *bool                   `json:"suspend,omitempty"`
+	Conditions       []WorkloadConditionView `json:"conditions,omitempty"`
+	StartTime        string                  `json:"startTime,omitempty"`
+	CompletionTime   string                  `json:"completionTime,omitempty"`
 }
 
 type JobDetailView struct {
-	Name             string                 `json:"name"`
-	Namespace        string                 `json:"namespace"`
-	Completions      int32                  `json:"completions"`
-	Parallelism      int32                  `json:"parallelism"`
-	Succeeded        int32                  `json:"succeeded"`
-	Failed           int32                  `json:"failed"`
-	Active           int32                  `json:"active"`
-	CompletionMode   string                 `json:"completionMode,omitempty"`
-	CreatedAt        string                 `json:"createdAt,omitempty"`
-	StartTime        string                 `json:"startTime,omitempty"`
-	CompletionTime   string                 `json:"completionTime,omitempty"`
-	Labels           map[string]string      `json:"labels,omitempty"`
-	Annotations      map[string]string      `json:"annotations,omitempty"`
-	Pods             []PodView              `json:"pods,omitempty"`
-	RelatedResources []WorkloadRelationView `json:"relatedResources,omitempty"`
-	AllowedActions   []string               `json:"allowedActions,omitempty"`
+	Name                    string                  `json:"name"`
+	Namespace               string                  `json:"namespace"`
+	Completions             int32                   `json:"completions"`
+	Parallelism             int32                   `json:"parallelism"`
+	Succeeded               int32                   `json:"succeeded"`
+	Failed                  int32                   `json:"failed"`
+	Active                  int32                   `json:"active"`
+	CompletionMode          string                  `json:"completionMode,omitempty"`
+	CreatedAt               string                  `json:"createdAt,omitempty"`
+	StartTime               string                  `json:"startTime,omitempty"`
+	CompletionTime          string                  `json:"completionTime,omitempty"`
+	Labels                  map[string]string       `json:"labels,omitempty"`
+	Annotations             map[string]string       `json:"annotations,omitempty"`
+	Pods                    []PodView               `json:"pods,omitempty"`
+	RelatedResources        []WorkloadRelationView  `json:"relatedResources,omitempty"`
+	AllowedActions          []string                `json:"allowedActions,omitempty"`
+	CompletionTarget        *int32                  `json:"completionTarget,omitempty"`
+	Suspend                 *bool                   `json:"suspend,omitempty"`
+	Conditions              []WorkloadConditionView `json:"conditions,omitempty"`
+	BackoffLimit            *int32                  `json:"backoffLimit,omitempty"`
+	ActiveDeadlineSeconds   *int64                  `json:"activeDeadlineSeconds,omitempty"`
+	TTLSecondsAfterFinished *int32                  `json:"ttlSecondsAfterFinished,omitempty"`
 }
 
 type CronJobView struct {
@@ -916,6 +950,7 @@ type NetworkTopologyView struct {
 }
 
 type NodeView struct {
+	Labels         map[string]string       `json:"labels,omitempty"`
 	Name           string                  `json:"name"`
 	Status         string                  `json:"status"`
 	Unschedulable  bool                    `json:"unschedulable"`
@@ -1379,6 +1414,16 @@ type SecretView struct {
 	AllowedActions []string `json:"allowedActions,omitempty"`
 }
 
+// SecretCertificateView contains public facts only; it cannot carry Secret data or PEM.
+type SecretCertificateView struct {
+	Name       string `json:"name"`
+	Namespace  string `json:"namespace"`
+	Status     string `json:"status"`
+	NotBefore  string `json:"notBefore,omitempty"`
+	NotAfter   string `json:"notAfter,omitempty"`
+	SelfSigned *bool  `json:"selfSigned,omitempty"`
+}
+
 type SecretDetailView struct {
 	Name        string            `json:"name"`
 	Namespace   string            `json:"namespace"`

package/resource/mutation_preconditions.go

@@ -0,0 +1,67 @@
+package resource
+
+import (
+	"fmt"
+	"strings"
+	"time"
+	"unicode"
+)
+
+// ResourceMutationPreconditions pins the object reviewed by the caller. Values
+// are opaque; in particular, resourceVersion must not be parsed as a number.
+type ResourceMutationPreconditions struct {
+	ExpectedUID             string `json:"expectedUid"`
+	ExpectedResourceVersion string `json:"expectedResourceVersion"`
+}
+
+func (p ResourceMutationPreconditions) Validate() error {
+	for _, value := range []string{p.ExpectedUID, p.ExpectedResourceVersion} {
+		if value == "" || len(value) > 256 || strings.IndexFunc(value, func(r rune) bool { return unicode.IsSpace(r) || unicode.IsControl(r) }) >= 0 {
+			return fmt.Errorf("expectedUid and expectedResourceVersion must be non-empty opaque values of at most 256 bytes without whitespace or control characters")
+		}
+	}
+	return nil
+}
+
+// ResourceIdentity deliberately contains no resource content or Secret data.
+type ResourceIdentity struct {
+	APIVersion        string     `json:"apiVersion"`
+	Kind              string     `json:"kind"`
+	Name              string     `json:"name"`
+	Namespace         string     `json:"namespace,omitempty"`
+	UID               string     `json:"uid"`
+	ResourceVersion   string     `json:"resourceVersion"`
+	DeletionTimestamp *time.Time `json:"deletionTimestamp,omitempty"`
+}
+
+type ConditionalResourceYAMLInput struct {
+	Content       string                        `json:"content"`
+	Preconditions ResourceMutationPreconditions `json:"preconditions"`
+}
+
+// ResourceDeletionReceipt reports acceptance for the frozen target only.
+// Callers must observe the target UID separately before reporting completion.
+type ResourceDeletionReceipt struct {
+	Accepted      bool                          `json:"accepted"`
+	State         string                        `json:"state"`
+	Kind          string                        `json:"kind"`
+	Name          string                        `json:"name"`
+	Namespace     string                        `json:"namespace,omitempty"`
+	Preconditions ResourceMutationPreconditions `json:"preconditions"`
+}
+
+// ConditionalResourceMutationRequest is the Agent transport. Core derives the
+// target from its authorized route rather than accepting an arbitrary API path.
+type ConditionalResourceMutationRequest struct {
+	Namespace     string                        `json:"namespace,omitempty"`
+	Kind          string                        `json:"kind"`
+	Name          string                        `json:"name"`
+	Preconditions ResourceMutationPreconditions `json:"preconditions"`
+}
+
+type ConditionalResourceYAMLRequest struct {
+	Namespace string `json:"namespace,omitempty"`
+	Kind      string `json:"kind"`
+	Name      string `json:"name"`
+	ConditionalResourceYAMLInput
+}