@opensoha/contracts 0.1.26 → 0.1.29

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

package/endpointcontrol/protocol.schema.json

@@ -0,0 +1,397 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensoha.dev/contracts/endpointcontrol/protocol.schema.json",
+  "title": "Endpoint channel controls",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/EndpointChannelDesired"
+    },
+    {
+      "$ref": "#/$defs/EndpointChannelReport"
+    }
+  ],
+  "$defs": {
+    "EndpointChannelControls": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "usb",
+        "print",
+        "clipboard"
+      ],
+      "properties": {
+        "usb": {
+          "type": "boolean"
+        },
+        "print": {
+          "type": "boolean"
+        },
+        "clipboard": {
+          "type": "boolean"
+        }
+      }
+    },
+    "EndpointChannelReceipt": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "scope",
+        "state",
+        "targets",
+        "controlled",
+        "reasonCode"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "enum": [
+            "usb",
+            "print",
+            "clipboard"
+          ]
+        },
+        "scope": {
+          "type": "string",
+          "enum": [
+            "current_usb_volumes",
+            "local_new_print_jobs",
+            "enrolled_console_win32"
+          ]
+        },
+        "state": {
+          "type": "string",
+          "enum": [
+            "off",
+            "controlled",
+            "partial",
+            "failed",
+            "unsupported",
+            "conflict",
+            "unconfigured",
+            "not_present"
+          ]
+        },
+        "targets": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 256
+        },
+        "controlled": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 256
+        },
+        "reasonCode": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9_]{0,63}$"
+        }
+      }
+    },
+    "EndpointChannelPolicy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "deviceId",
+        "revision",
+        "publishedVersion",
+        "draft",
+        "updatedAt"
+      ],
+      "properties": {
+        "deviceId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
+        },
+        "revision": {
+          "type": "integer",
+          "format": "int64",
+          "minimum": 0
+        },
+        "publishedVersion": {
+          "type": "integer",
+          "format": "int64",
+          "minimum": 0
+        },
+        "draft": {
+          "$ref": "#/$defs/EndpointChannelControls"
+        },
+        "published": {
+          "$ref": "#/$defs/EndpointChannelControls"
+        },
+        "updatedAt": {
+          "type": "string",
+          "format": "date-time"
+        }
+      }
+    },
+    "EndpointChannelDesired": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "deviceId",
+        "runtimeId",
+        "credentialId",
+        "policyVersion",
+        "challenge",
+        "controls",
+        "issuedAt",
+        "validUntil",
+        "configured"
+      ],
+      "properties": {
+        "schemaVersion": {
+          "type": "string",
+          "const": "endpoint-controls/v1alpha1"
+        },
+        "deviceId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
+        },
+        "runtimeId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
+        },
+        "credentialId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
+        },
+        "policyVersion": {
+          "type": "integer",
+          "format": "int64",
+          "minimum": 0
+        },
+        "challenge": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9_-]{43}$"
+        },
+        "controls": {
+          "$ref": "#/$defs/EndpointChannelControls"
+        },
+        "issuedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "validUntil": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "configured": {
+          "type": "boolean",
+          "description": "False means unconfigured; never a release. Release requires a higher explicit published version."
+        }
+      }
+    },
+    "EndpointChannelReport": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "deviceId",
+        "runtimeId",
+        "credentialId",
+        "policyVersion",
+        "challenge",
+        "observedAt",
+        "channels"
+      ],
+      "properties": {
+        "schemaVersion": {
+          "type": "string",
+          "const": "endpoint-controls/v1alpha1"
+        },
+        "deviceId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
+        },
+        "runtimeId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
+        },
+        "credentialId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
+        },
+        "policyVersion": {
+          "type": "integer",
+          "format": "int64",
+          "minimum": 0
+        },
+        "challenge": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9_-]{43}$"
+        },
+        "observedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "channels": {
+          "type": "array",
+          "minItems": 3,
+          "maxItems": 3,
+          "items": {
+            "$ref": "#/$defs/EndpointChannelReceipt"
+          }
+        }
+      }
+    },
+    "EndpointChannelView": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "policy",
+        "fresh",
+        "runtimeCount",
+        "pendingRuntimeCount"
+      ],
+      "properties": {
+        "policy": {
+          "$ref": "#/$defs/EndpointChannelPolicy"
+        },
+        "receipt": {
+          "$ref": "#/$defs/EndpointChannelObservation"
+        },
+        "receivedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "fresh": {
+          "type": "boolean"
+        },
+        "runtimeCount": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "pendingRuntimeCount": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    },
+    "EndpointChannelSaveInput": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "expectedRevision",
+        "draft"
+      ],
+      "properties": {
+        "expectedRevision": {
+          "type": "integer",
+          "format": "int64",
+          "minimum": 0
+        },
+        "draft": {
+          "$ref": "#/$defs/EndpointChannelControls"
+        }
+      }
+    },
+    "EndpointChannelPublishInput": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "expectedRevision"
+      ],
+      "properties": {
+        "expectedRevision": {
+          "type": "integer",
+          "format": "int64",
+          "minimum": 1
+        }
+      }
+    },
+    "EndpointChannelPolicyEnvelope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "data"
+      ],
+      "properties": {
+        "data": {
+          "$ref": "#/$defs/EndpointChannelPolicy"
+        }
+      }
+    },
+    "EndpointChannelDesiredEnvelope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "data"
+      ],
+      "properties": {
+        "data": {
+          "$ref": "#/$defs/EndpointChannelDesired"
+        }
+      }
+    },
+    "EndpointChannelViewEnvelope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "data"
+      ],
+      "properties": {
+        "data": {
+          "$ref": "#/$defs/EndpointChannelView"
+        }
+      }
+    },
+    "EndpointChannelObservation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "runtimeId",
+        "credentialId",
+        "policyVersion",
+        "observedAt",
+        "channels"
+      ],
+      "properties": {
+        "runtimeId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
+        },
+        "credentialId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
+        },
+        "policyVersion": {
+          "type": "integer",
+          "format": "int64",
+          "minimum": 0
+        },
+        "observedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "channels": {
+          "type": "array",
+          "minItems": 3,
+          "maxItems": 3,
+          "items": {
+            "$ref": "#/$defs/EndpointChannelReceipt"
+          }
+        }
+      }
+    }
+  }
+}

package/fixtures/json-schema/endpoint-controls/invalid/controls.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": "endpoint-controls/v1alpha1",
+  "deviceId": "device",
+  "runtimeId": "endpoint",
+  "credentialId": "credential",
+  "policyVersion": 1,
+  "challenge": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "controls": {
+    "usb": true,
+    "print": true,
+    "clipboard": true
+  },
+  "issuedAt": "2026-10-28T00:00:00Z",
+  "validUntil": "2026-10-28T00:01:00Z",
+  "content": "must not transport file content"
+}

package/fixtures/json-schema/endpoint-controls/invalid/missing-channel-decision.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": "endpoint-controls/v1alpha1",
+  "deviceId": "device",
+  "runtimeId": "endpoint",
+  "credentialId": "credential",
+  "policyVersion": 1,
+  "challenge": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "controls": {
+    "usb": true,
+    "print": true
+  },
+  "issuedAt": "2026-10-28T00:00:00Z",
+  "validUntil": "2026-10-28T00:01:00Z",
+  "configured": true
+}

package/fixtures/json-schema/endpoint-controls/invalid/receipt-content.json

@@ -0,0 +1,36 @@
+{
+  "schemaVersion": "endpoint-controls/v1alpha1",
+  "deviceId": "device",
+  "runtimeId": "endpoint",
+  "credentialId": "credential",
+  "policyVersion": 1,
+  "challenge": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "observedAt": "2026-10-28T00:00:00Z",
+  "channels": [
+    {
+      "name": "usb",
+      "scope": "current_usb_volumes",
+      "state": "controlled",
+      "targets": 1,
+      "controlled": 1,
+      "reasonCode": "native_scope_only"
+    },
+    {
+      "name": "print",
+      "scope": "local_new_print_jobs",
+      "state": "controlled",
+      "targets": 1,
+      "controlled": 1,
+      "reasonCode": "native_scope_only"
+    },
+    {
+      "name": "clipboard",
+      "scope": "enrolled_console_win32",
+      "state": "controlled",
+      "targets": 1,
+      "controlled": 1,
+      "reasonCode": "native_scope_only"
+    }
+  ],
+  "clipboardText": "forbidden"
+}

package/fixtures/json-schema/endpoint-controls/valid/controls.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": "endpoint-controls/v1alpha1",
+  "deviceId": "device",
+  "runtimeId": "endpoint",
+  "credentialId": "credential",
+  "policyVersion": 1,
+  "challenge": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "controls": {
+    "usb": true,
+    "print": true,
+    "clipboard": true
+  },
+  "issuedAt": "2026-10-28T00:00:00Z",
+  "validUntil": "2026-10-28T00:01:00Z",
+  "configured": true
+}