@opensoha/contracts 0.1.25 → 0.1.27

package/delivery/document.schema.json

@@ -177,6 +177,9 @@
           "default": true,
           "type": "boolean"
         },
+        "migrationPolicy": {
+          "$ref": "#/$defs/TemplateMigrationPolicy"
+        },
         "variableSchema": {
           "additionalProperties": {
             "$ref": "#/$defs/DeliveryBuildVariableSchema"
@@ -317,6 +320,9 @@
         "health": {
           "$ref": "#/$defs/DeploymentTemplateHealth"
         },
+        "migrationPolicy": {
+          "$ref": "#/$defs/TemplateMigrationPolicy"
+        },
         "parameterSchema": {
           "$ref": "#/$defs/TemplateParameterSchema"
         },
@@ -804,21 +810,68 @@
       "additionalProperties": false,
       "allOf": [
         {
-          "if": {
+          "else": {
+            "allOf": [
+              {
+                "if": {
+                  "properties": {
+                    "action": {
+                      "enum": [
+                        "build_deploy",
+                        "deploy",
+                        "config_update"
+                      ]
+                    }
+                  }
+                },
+                "then": {
+                  "required": [
+                    "applicationEnvironmentId"
+                  ]
+                }
+              }
+            ],
             "properties": {
-              "action": {
-                "enum": [
-                  "build_deploy",
-                  "deploy",
-                  "config_update"
-                ]
+              "serviceId": {
+                "minLength": 1,
+                "type": "string"
               }
             }
           },
-          "then": {
+          "if": {
             "required": [
-              "applicationEnvironmentId"
+              "templateCandidateId"
             ]
+          },
+          "then": {
+            "not": {
+              "anyOf": [
+                {
+                  "required": [
+                    "helmRevision"
+                  ]
+                },
+                {
+                  "required": [
+                    "buildArgs"
+                  ]
+                },
+                {
+                  "required": [
+                    "repositoryRefs"
+                  ]
+                }
+              ]
+            },
+            "properties": {
+              "action": {
+                "const": "config_update"
+              },
+              "releaseBundleId": {
+                "maxLength": 0,
+                "type": "string"
+              }
+            }
           }
         },
         {
@@ -897,6 +950,10 @@
           "type": "array"
         },
         "serviceId": {
+          "type": "string"
+        },
+        "templateCandidateId": {
+          "maxLength": 256,
           "minLength": 1,
           "type": "string"
         }
@@ -1068,6 +1125,9 @@
         "enabled": {
           "default": true,
           "type": "boolean"
+        },
+        "migrationPolicy": {
+          "$ref": "#/$defs/TemplateMigrationPolicy"
         }
       },
       "required": [
@@ -1376,6 +1436,64 @@
       },
       "type": "object"
     },
+    "TemplateMigrationPolicy": {
+      "additionalProperties": false,
+      "if": {
+        "anyOf": [
+          {
+            "properties": {
+              "sequential": {
+                "const": true
+              }
+            },
+            "required": [
+              "sequential"
+            ]
+          },
+          {
+            "properties": {
+              "irreversible": {
+                "const": true
+              }
+            },
+            "required": [
+              "irreversible"
+            ]
+          }
+        ]
+      },
+      "properties": {
+        "guide": {
+          "description": "Human migration/recovery instructions. Never executed as a script.",
+          "maxLength": 2000,
+          "type": "string"
+        },
+        "irreversible": {
+          "description": "Forward changes require approval; ordinary rollback across this boundary is forbidden.",
+          "type": "boolean"
+        },
+        "sequential": {
+          "description": "Must cross this boundary as adjacent published versions; approval cannot waive it.",
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "sequential",
+        "irreversible"
+      ],
+      "then": {
+        "properties": {
+          "guide": {
+            "minLength": 1,
+            "pattern": "\\S"
+          }
+        },
+        "required": [
+          "guide"
+        ]
+      },
+      "type": "object"
+    },
     "TemplateParameterSchema": {
       "additionalProperties": false,
       "description": "Restricted JSON Schema. Objects reject undeclared keys unless mapValues specifies their schema. secret_reference accepts only a namespaced Secret name/key reference, never a plaintext credential. External references and executable expressions are unsupported.",

package/endpointcontrol/decode.go

@@ -0,0 +1,64 @@
+package endpointcontrol
+
+import (
+	"errors"
+	"time"
+)
+
+// Required booleans must be present, including explicit false. Missing input
+// must never become a newer all-off policy through Go zero values.
+func (c *Controls) UnmarshalJSON(raw []byte) error {
+	var w struct {
+		USB       *bool `json:"usb"`
+		Print     *bool `json:"print"`
+		Clipboard *bool `json:"clipboard"`
+	}
+	if err := Decode(raw, &w); err != nil {
+		return err
+	}
+	if w.USB == nil || w.Print == nil || w.Clipboard == nil {
+		return errors.New("all native channel decisions are required")
+	}
+	*c = Controls{USB: *w.USB, Print: *w.Print, Clipboard: *w.Clipboard}
+	return nil
+}
+func (d *Desired) UnmarshalJSON(raw []byte) error {
+	var w struct {
+		Configured    *bool      `json:"configured"`
+		SchemaVersion string     `json:"schemaVersion"`
+		DeviceID      string     `json:"deviceId"`
+		RuntimeID     string     `json:"runtimeId"`
+		CredentialID  string     `json:"credentialId"`
+		PolicyVersion *int64     `json:"policyVersion"`
+		Controls      *Controls  `json:"controls"`
+		Challenge     string     `json:"challenge"`
+		IssuedAt      *time.Time `json:"issuedAt"`
+		ValidUntil    *time.Time `json:"validUntil"`
+	}
+	if err := Decode(raw, &w); err != nil {
+		return err
+	}
+	if w.Configured == nil || w.PolicyVersion == nil || w.Controls == nil || w.IssuedAt == nil || w.ValidUntil == nil {
+		return errors.New("native channel envelope has missing required fields")
+	}
+	*d = Desired{Configured: *w.Configured, SchemaVersion: w.SchemaVersion, DeviceID: w.DeviceID, RuntimeID: w.RuntimeID, CredentialID: w.CredentialID, PolicyVersion: *w.PolicyVersion, Controls: *w.Controls, Challenge: w.Challenge, IssuedAt: *w.IssuedAt, ValidUntil: *w.ValidUntil}
+	return nil
+}
+func (c *Channel) UnmarshalJSON(raw []byte) error {
+	var w struct {
+		Name       string `json:"name"`
+		Scope      string `json:"scope"`
+		State      string `json:"state"`
+		Targets    *int   `json:"targets"`
+		Controlled *int   `json:"controlled"`
+		ReasonCode string `json:"reasonCode"`
+	}
+	if err := Decode(raw, &w); err != nil {
+		return err
+	}
+	if w.Targets == nil || w.Controlled == nil {
+		return errors.New("native channel counts are required")
+	}
+	*c = Channel{Name: w.Name, Scope: w.Scope, State: w.State, Targets: *w.Targets, Controlled: *w.Controlled, ReasonCode: w.ReasonCode}
+	return nil
+}

package/endpointcontrol/models.go

@@ -0,0 +1,138 @@
+// Package endpointcontrol owns the bounded native endpoint-channel protocol.
+package endpointcontrol
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"io"
+	"regexp"
+	"time"
+)
+
+const Version = "endpoint-controls/v1alpha1"
+const Capability = "windows-channel-controls-v1"
+
+type Controls struct {
+	USB       bool `json:"usb"`
+	Print     bool `json:"print"`
+	Clipboard bool `json:"clipboard"`
+}
+type Policy struct {
+	DeviceID         string    `json:"deviceId"`
+	Revision         int64     `json:"revision"`
+	PublishedVersion int64     `json:"publishedVersion"`
+	Draft            Controls  `json:"draft"`
+	Published        *Controls `json:"published,omitempty"`
+	UpdatedAt        time.Time `json:"updatedAt"`
+}
+type SaveInput struct {
+	ExpectedRevision int64    `json:"expectedRevision"`
+	Draft            Controls `json:"draft"`
+}
+type PublishInput struct {
+	ExpectedRevision int64 `json:"expectedRevision"`
+}
+type Desired struct {
+	Configured    bool      `json:"configured"`
+	SchemaVersion string    `json:"schemaVersion"`
+	DeviceID      string    `json:"deviceId"`
+	RuntimeID     string    `json:"runtimeId"`
+	CredentialID  string    `json:"credentialId"`
+	PolicyVersion int64     `json:"policyVersion"`
+	Controls      Controls  `json:"controls"`
+	Challenge     string    `json:"challenge"`
+	IssuedAt      time.Time `json:"issuedAt"`
+	ValidUntil    time.Time `json:"validUntil"`
+}
+type Channel struct {
+	Name       string `json:"name"`
+	Scope      string `json:"scope"`
+	State      string `json:"state"`
+	Targets    int    `json:"targets"`
+	Controlled int    `json:"controlled"`
+	ReasonCode string `json:"reasonCode"`
+}
+type Receipt struct {
+	SchemaVersion string    `json:"schemaVersion"`
+	DeviceID      string    `json:"deviceId"`
+	RuntimeID     string    `json:"runtimeId"`
+	CredentialID  string    `json:"credentialId"`
+	PolicyVersion int64     `json:"policyVersion"`
+	Challenge     string    `json:"challenge"`
+	ObservedAt    time.Time `json:"observedAt"`
+	Channels      []Channel `json:"channels"`
+}
+type View struct {
+	Policy              Policy       `json:"policy"`
+	Receipt             *Observation `json:"receipt,omitempty"`
+	ReceivedAt          *time.Time   `json:"receivedAt,omitempty"`
+	Fresh               bool         `json:"fresh"`
+	RuntimeCount        int          `json:"runtimeCount"`
+	PendingRuntimeCount int          `json:"pendingRuntimeCount"`
+}
+type Observation struct {
+	RuntimeID     string    `json:"runtimeId"`
+	CredentialID  string    `json:"credentialId"`
+	PolicyVersion int64     `json:"policyVersion"`
+	ObservedAt    time.Time `json:"observedAt"`
+	Channels      []Channel `json:"channels"`
+}
+
+var identifier = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$`)
+var challenge = regexp.MustCompile(`^[A-Za-z0-9_-]{43}$`)
+var reason = regexp.MustCompile(`^[a-z][a-z0-9_]{0,63}$`)
+
+func Decode(raw []byte, out any) error {
+	if len(raw) > 32768 {
+		return errors.New("endpoint channel message too large")
+	}
+	d := json.NewDecoder(bytes.NewReader(raw))
+	d.DisallowUnknownFields()
+	if err := d.Decode(out); err != nil {
+		return err
+	}
+	if d.Decode(new(any)) != io.EOF {
+		return errors.New("trailing channel message")
+	}
+	return nil
+}
+func ValidDesired(d Desired, now time.Time) bool {
+	return (d.Configured && d.PolicyVersion > 0 || !d.Configured && d.PolicyVersion == 0) && validIdentity(d.SchemaVersion, d.DeviceID, d.RuntimeID, d.CredentialID, d.PolicyVersion, d.Challenge) && !d.IssuedAt.After(now.Add(30*time.Second)) && d.ValidUntil.After(now) && d.ValidUntil.After(d.IssuedAt) && d.ValidUntil.Sub(d.IssuedAt) <= time.Minute
+}
+func ValidReceipt(r Receipt, now time.Time) bool {
+	if !validIdentity(r.SchemaVersion, r.DeviceID, r.RuntimeID, r.CredentialID, r.PolicyVersion, r.Challenge) || len(r.Channels) != 3 || r.ObservedAt.Before(now.Add(-time.Minute)) || r.ObservedAt.After(now.Add(30*time.Second)) {
+		return false
+	}
+	seen := map[string]bool{}
+	for _, c := range r.Channels {
+		if seen[c.Name] || !ValidChannel(c) {
+			return false
+		}
+		seen[c.Name] = true
+	}
+	return seen["usb"] && seen["print"] && seen["clipboard"]
+}
+func validIdentity(version, device, runtime, credential string, revision int64, nonce string) bool {
+	return version == Version && identifier.MatchString(device) && identifier.MatchString(runtime) && identifier.MatchString(credential) && revision >= 0 && challenge.MatchString(nonce)
+}
+func ValidChannel(c Channel) bool {
+	scopes := map[string]string{"usb": "current_usb_volumes", "print": "local_new_print_jobs", "clipboard": "enrolled_console_win32"}
+	if scopes[c.Name] == "" || c.Scope != scopes[c.Name] || c.Targets < 0 || c.Targets > 256 || c.Controlled < 0 || c.Controlled > c.Targets || !reason.MatchString(c.ReasonCode) {
+		return false
+	}
+	if c.State == "controlled" && (c.Targets == 0 || c.Controlled != c.Targets) {
+		return false
+	}
+	if (c.State == "off" || c.State == "unconfigured" || c.State == "not_present") && c.Controlled != 0 {
+		return false
+	}
+	if (c.State == "unconfigured" || c.State == "not_present") && c.Targets != 0 {
+		return false
+	}
+	switch c.State {
+	case "off", "unconfigured", "not_present", "controlled", "partial", "failed", "unsupported", "conflict":
+		return true
+	}
+	return false
+}

package/endpointcontrol/models_test.go

@@ -0,0 +1,51 @@
+package endpointcontrol
+
+import (
+	"testing"
+	"time"
+)
+
+func TestNativeReceiptCannotClaimContradictoryControl(t *testing.T) {
+	cases := []Channel{
+		{Name: "usb", Scope: "current_usb_volumes", State: "controlled", Targets: 1, Controlled: 0, ReasonCode: "native_scope_only"},
+		{Name: "usb", Scope: "current_usb_volumes", State: "controlled", Targets: 0, Controlled: 0, ReasonCode: "native_scope_only"},
+		{Name: "clipboard", Scope: "current_usb_volumes", State: "controlled", Targets: 1, Controlled: 1, ReasonCode: "native_scope_only"},
+		{Name: "print", Scope: "local_new_print_jobs", State: "off", Targets: 1, Controlled: 1, ReasonCode: "disabled"},
+	}
+	for _, c := range cases {
+		if ValidChannel(c) {
+			t.Fatalf("contradictory control accepted: %+v", c)
+		}
+	}
+	if !ValidChannel(Channel{Name: "clipboard", Scope: "enrolled_console_win32", State: "controlled", Targets: 1, Controlled: 1, ReasonCode: "native_scope_only"}) {
+		t.Fatal("bounded native control rejected")
+	}
+}
+func TestUnconfiguredIsNotAPublishedRelease(t *testing.T) {
+	now := time.Now().UTC()
+	d := Desired{SchemaVersion: Version, DeviceID: "d", RuntimeID: "r", CredentialID: "c", Challenge: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", IssuedAt: now, ValidUntil: now.Add(time.Minute)}
+	if !ValidDesired(d, now) {
+		t.Fatal("unconfigured envelope rejected")
+	}
+	d.PolicyVersion = 1
+	if ValidDesired(d, now) {
+		t.Fatal("positive unpublished revision accepted")
+	}
+	d.Configured = true
+	if !ValidDesired(d, now) {
+		t.Fatal("explicit published release rejected")
+	}
+}
+
+func TestMissingBooleanCannotDecodeAsRelease(t *testing.T) {
+	var controls Controls
+	for _, raw := range []string{`{}`, `{"usb":false,"print":false}`, `{"usb":false,"print":false,"clipboard":null}`} {
+		if Decode([]byte(raw), &controls) == nil {
+			t.Fatal("incomplete channel decisions accepted", raw)
+		}
+	}
+	var desired Desired
+	if Decode([]byte(`{"configured":true,"schemaVersion":"endpoint-controls/v1alpha1","deviceId":"device","runtimeId":"runtime","credentialId":"credential","policyVersion":99,"challenge":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","issuedAt":"2026-10-28T00:00:00Z","validUntil":"2026-10-28T00:01:00Z"}`), &desired) == nil {
+		t.Fatal("missing controls became release")
+	}
+}