@opensoha/contracts 0.1.25 → 0.1.27

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/examples/relations_compat_test.go

@@ -0,0 +1,18 @@
+package examples
+
+import (
+	sdk "github.com/opensoha/soha-contracts/gen/go/sohaapi"
+	"testing"
+)
+
+func TestRelationAdditionPreservesPublishedEnumNames(t *testing.T) {
+	values := []sdk.PersonalGuestRuntimeInputKind{sdk.Browser, sdk.Docker, sdk.Execute, sdk.FileRead, sdk.FileWrite}
+	for i, want := range []string{"browser", "docker", "execute", "file_read", "file_write"} {
+		if string(values[i]) != want {
+			t.Fatalf("published enum %d changed", i)
+		}
+	}
+	if sdk.JSON != sdk.ExportDeliveryDocumentParamsFormatJSON || sdk.Yaml != sdk.ExportDeliveryDocumentParamsFormatYaml {
+		t.Fatal("published format aliases changed")
+	}
+}

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

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

@@ -0,0 +1,35 @@
+{
+  "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"
+    }
+  ]
+}

package/fixtures/json-schema/network-runtime-protocol/invalid/eap-activate-bad-fingerprint.json

@@ -0,0 +1,14 @@
+{
+  "schemaVersion": "network-runtime/v1alpha1",
+  "messageId": "presence-1",
+  "messageType": "eap.certificate.activate.request",
+  "producerId": "endpoint-lab",
+  "runtimeId": "endpoint-lab",
+  "runtimeKind": "endpoint",
+  "occurredAt": "2026-10-14T00:00:00Z",
+  "expiresAt": "2026-10-14T00:00:30Z",
+  "payload": {
+    "credentialId": "eap-credential-1",
+    "fingerprint": "sha256:bad"
+  }
+}

package/fixtures/json-schema/network-runtime-protocol/invalid/eap-gateway-request.json

@@ -0,0 +1,14 @@
+{
+  "schemaVersion": "network-runtime/v1alpha1",
+  "messageId": "presence-1",
+  "messageType": "eap.certificate.request",
+  "producerId": "endpoint-lab",
+  "runtimeId": "endpoint-lab",
+  "runtimeKind": "gateway",
+  "occurredAt": "2026-10-14T00:00:00Z",
+  "expiresAt": "2026-10-14T00:00:30Z",
+  "payload": {
+    "requestId": "eap-rotation-1",
+    "csrPem": "-----BEGIN CERTIFICATE REQUEST-----\nAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\n-----END CERTIFICATE REQUEST-----\n"
+  }
+}

package/fixtures/json-schema/network-runtime-protocol/invalid/eap-private-key-request.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": "network-runtime/v1alpha1",
+  "messageId": "presence-1",
+  "messageType": "eap.certificate.request",
+  "producerId": "endpoint-lab",
+  "runtimeId": "endpoint-lab",
+  "runtimeKind": "endpoint",
+  "occurredAt": "2026-10-14T00:00:00Z",
+  "expiresAt": "2026-10-14T00:00:30Z",
+  "payload": {
+    "requestId": "eap-rotation-1",
+    "csrPem": "-----BEGIN CERTIFICATE REQUEST-----\nAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\n-----END CERTIFICATE REQUEST-----\n",
+    "privateKey": "never-transmit"
+  }
+}

package/fixtures/json-schema/network-runtime-protocol/invalid/eap-profile-without-eap-credential.json

@@ -0,0 +1,22 @@
+{
+  "schemaVersion": "network-runtime/v1alpha1",
+  "messageId": "msg-enroll-wireguard-0001",
+  "messageType": "runtime.enroll.request",
+  "producerId": "endpoint-alice",
+  "runtimeId": "endpoint-alice",
+  "runtimeKind": "endpoint",
+  "occurredAt": "2026-09-02T08:00:00Z",
+  "expiresAt": "2026-09-02T08:05:00Z",
+  "payload": {
+    "enrollmentId": "enrollment-alice",
+    "challengeId": "challenge-alice",
+    "deviceId": "device-alice-laptop",
+    "devicePublicKey": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA7qY8R9gAwRQmJau0p7uB8mVJwA6m3i3zYvRrV7lIl1E=\n-----END PUBLIC KEY-----",
+    "wireguardPublicKey": "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=",
+    "platform": "macos",
+    "clientVersion": "0.2.0",
+    "capabilities": [
+      "eap-profile-v1"
+    ]
+  }
+}

package/fixtures/json-schema/network-runtime-protocol/invalid/endpoint-dns-observation.json

@@ -0,0 +1,25 @@
+{
+  "schemaVersion": "network-runtime/v1alpha1",
+  "messageId": "msg-dns-1",
+  "messageType": "dns.observations",
+  "producerId": "gateway-site-a",
+  "runtimeId": "gateway-site-a",
+  "runtimeKind": "endpoint",
+  "occurredAt": "2026-09-02T08:00:00Z",
+  "expiresAt": "2026-09-02T08:05:00Z",
+  "payload": {
+    "configurationVersion": 12,
+    "policyVersion": 7,
+    "observations": [
+      {
+        "resourceId": "resource-payroll",
+        "hostname": "payroll.example.internal",
+        "addresses": [
+          "fd20::10"
+        ],
+        "observedAt": "2026-09-02T08:00:00Z",
+        "ttlSeconds": 60
+      }
+    ]
+  }
+}

package/fixtures/json-schema/network-runtime-protocol/invalid/gateway-presence.json

@@ -0,0 +1,22 @@
+{
+  "schemaVersion": "network-runtime/v1alpha1",
+  "messageId": "presence-1",
+  "messageType": "endpoint.presence.request",
+  "producerId": "endpoint-lab",
+  "runtimeId": "endpoint-lab",
+  "runtimeKind": "gateway",
+  "occurredAt": "2026-10-14T00:00:00Z",
+  "expiresAt": "2026-10-14T00:00:30Z",
+  "payload": {
+    "deviceId": "device-lab",
+    "bootId": "boot-1",
+    "sequence": 1,
+    "status": "healthy",
+    "configurationVersion": 1,
+    "policyVersion": 1,
+    "uiState": "unknown",
+    "capabilities": [
+      "endpoint-presence-v1"
+    ]
+  }
+}