@opensoha/contracts 0.1.16 → 0.1.17

package/compat/json-schema-ecosystem-0.1.0.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.16",
+  "version": "0.1.17",
   "schemas": {
     "plugins/plugin-manifest.schema.json": {
       "rootRequired": ["id", "name", "publisher", "type", "version"],

package/compat/openapi-loose-boundaries-0.1.0.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.16",
+  "version": "0.1.17",
   "generatedFrom": "openapi/soha-api.yaml",
   "entries": [
     {

package/fixtures/json-schema/network-ingest-event/invalid/duplicate-event.json

@@ -0,0 +1,33 @@
+{
+  "schemaVersion": "network-ingest/v1alpha1",
+  "batchId": "batch-duplicate-0001",
+  "producerId": "gateway-site-a",
+  "producerKind": "gateway",
+  "sentAt": "2026-09-02T08:01:00Z",
+  "events": [
+    {
+      "id": "event-duplicate-0001",
+      "type": "runtime.heartbeat",
+      "sequence": 101,
+      "occurredAt": "2026-09-02T08:00:59Z",
+      "payload": {
+        "status": "healthy",
+        "configurationVersion": 12,
+        "policyVersion": 7,
+        "uptimeSeconds": 3600
+      }
+    },
+    {
+      "id": "event-duplicate-0001",
+      "type": "runtime.heartbeat",
+      "sequence": 101,
+      "occurredAt": "2026-09-02T08:00:59Z",
+      "payload": {
+        "status": "healthy",
+        "configurationVersion": 12,
+        "policyVersion": 7,
+        "uptimeSeconds": 3600
+      }
+    }
+  ]
+}

package/fixtures/json-schema/network-ingest-event/invalid/message-payload-mismatch.json

@@ -0,0 +1,23 @@
+{
+  "schemaVersion": "network-ingest/v1alpha1",
+  "batchId": "batch-mismatch-0001",
+  "producerId": "gateway-site-a",
+  "producerKind": "gateway",
+  "sentAt": "2026-09-02T08:01:00Z",
+  "events": [
+    {
+      "id": "event-mismatch-0001",
+      "type": "runtime.heartbeat",
+      "sequence": 104,
+      "occurredAt": "2026-09-02T08:01:00Z",
+      "payload": {
+        "sessionId": "session-0001",
+        "resourceId": "resource-payroll",
+        "protocol": "tcp",
+        "destinationPort": 443,
+        "state": "denied",
+        "reasonCode": "missing_resource_lease"
+      }
+    }
+  ]
+}

package/fixtures/json-schema/network-ingest-event/invalid/password.json

@@ -0,0 +1,22 @@
+{
+  "schemaVersion": "network-ingest/v1alpha1",
+  "batchId": "batch-radius-secret",
+  "producerId": "freeradius-site-a",
+  "producerKind": "freeradius",
+  "sentAt": "2026-09-02T08:01:00Z",
+  "events": [
+    {
+      "id": "event-accounting-secret",
+      "type": "radius.accounting",
+      "sequence": 32,
+      "occurredAt": "2026-09-02T08:00:58Z",
+      "payload": {
+        "statusType": "start",
+        "accountingSessionId": "radius-session-0001",
+        "nasId": "nas-site-a-wifi",
+        "sessionTimeSeconds": 0,
+        "userPassword": "must-never-enter-ingest"
+      }
+    }
+  ]
+}

package/fixtures/json-schema/network-ingest-event/invalid/proxy-flow-destination.json

@@ -0,0 +1,28 @@
+{
+  "schemaVersion": "network-ingest/v1alpha1",
+  "batchId": "batch-endpoint-proxy-invalid",
+  "producerId": "endpoint-0001",
+  "producerKind": "endpoint",
+  "sentAt": "2026-09-02T08:01:00Z",
+  "events": [
+    {
+      "id": "event-proxy-flow-invalid",
+      "type": "proxy.flow.aggregate",
+      "sequence": 103,
+      "occurredAt": "2026-09-02T08:01:00Z",
+      "payload": {
+        "windowStartedAt": "2026-09-02T08:00:00Z",
+        "windowEndedAt": "2026-09-02T08:01:00Z",
+		"engine": "mihomo",
+        "profileId": "mihomo-default",
+        "profileRevision": 3,
+        "mode": "app_subscription",
+        "selectedProxy": "edge-a",
+        "uploadBytes": 1024,
+        "downloadBytes": 4096,
+        "activeConnections": 2,
+        "destinationHost": "private.example.test"
+      }
+    }
+  ]
+}

package/fixtures/json-schema/network-ingest-event/valid/endpoint-proxy-flow.json

@@ -0,0 +1,27 @@
+{
+  "schemaVersion": "network-ingest/v1alpha1",
+  "batchId": "batch-endpoint-proxy-0001",
+  "producerId": "endpoint-0001",
+  "producerKind": "endpoint",
+  "sentAt": "2026-09-02T08:01:00Z",
+  "events": [
+    {
+      "id": "event-proxy-flow-0001",
+      "type": "proxy.flow.aggregate",
+      "sequence": 102,
+      "occurredAt": "2026-09-02T08:01:00Z",
+      "payload": {
+        "windowStartedAt": "2026-09-02T08:00:00Z",
+        "windowEndedAt": "2026-09-02T08:01:00Z",
+		"engine": "mihomo",
+        "profileId": "mihomo-default",
+        "profileRevision": 3,
+        "mode": "app_subscription",
+        "selectedProxy": "edge-a",
+        "uploadBytes": 1024,
+        "downloadBytes": 4096,
+        "activeConnections": 2
+      }
+    }
+  ]
+}

package/fixtures/json-schema/network-ingest-event/valid/freeradius-accounting.json

@@ -0,0 +1,25 @@
+{
+  "schemaVersion": "network-ingest/v1alpha1",
+  "batchId": "batch-radius-0001",
+  "producerId": "freeradius-site-a",
+  "producerKind": "freeradius",
+  "sentAt": "2026-09-02T08:01:00Z",
+  "events": [
+    {
+      "id": "event-accounting-0001",
+      "type": "radius.accounting",
+      "sequence": 31,
+      "occurredAt": "2026-09-02T08:00:58Z",
+      "payload": {
+        "statusType": "start",
+        "accountingSessionId": "radius-session-0001",
+        "nasId": "nas-site-a-wifi",
+        "userId": "user-alice",
+        "deviceId": "device-alice-laptop",
+        "sessionTimeSeconds": 0,
+        "inputOctets": 0,
+        "outputOctets": 0
+      }
+    }
+  ]
+}

package/fixtures/json-schema/network-ingest-event/valid/gateway.json

@@ -0,0 +1,53 @@
+{
+  "schemaVersion": "network-ingest/v1alpha1",
+  "batchId": "batch-gateway-0001",
+  "producerId": "gateway-site-a",
+  "producerKind": "gateway",
+  "sentAt": "2026-09-02T08:01:00Z",
+  "events": [
+    {
+      "id": "event-heartbeat-0001",
+      "type": "runtime.heartbeat",
+      "sequence": 101,
+      "occurredAt": "2026-09-02T08:00:59Z",
+      "payload": {
+        "status": "healthy",
+        "configurationVersion": 12,
+        "policyVersion": 7,
+        "uptimeSeconds": 3600
+      }
+    },
+    {
+      "id": "event-flow-0001",
+      "type": "network.flow.aggregate",
+      "sequence": 102,
+      "occurredAt": "2026-09-02T08:01:00Z",
+      "payload": {
+        "windowStartedAt": "2026-09-02T08:00:00Z",
+        "windowEndedAt": "2026-09-02T08:01:00Z",
+        "sessionId": "session-0001",
+        "resourceId": "resource-payroll",
+        "direction": "egress",
+        "protocol": "tcp",
+        "bytes": 4096,
+        "packets": 24,
+        "connections": 2,
+        "deniedConnections": 0
+      }
+    },
+    {
+      "id": "event-connection-0001",
+      "type": "network.connection.summary",
+      "sequence": 103,
+      "occurredAt": "2026-09-02T08:01:00Z",
+      "payload": {
+        "sessionId": "session-0001",
+        "resourceId": "resource-payroll",
+        "protocol": "tcp",
+        "destinationPort": 443,
+        "state": "closed",
+        "reasonCode": "client_closed"
+      }
+    }
+  ]
+}

package/fixtures/json-schema/network-radius-accounting/invalid/password.json

@@ -0,0 +1,9 @@
+{
+  "schemaVersion": "network-radius-accounting/v1alpha1",
+  "eventTimestamp": 1788336000,
+  "statusType": "start",
+  "accountingSessionId": "session-1",
+  "nasId": "nas-hq",
+  "sessionTimeSeconds": 0,
+  "userPassword": "must-not-cross-boundary"
+}

package/fixtures/json-schema/network-radius-accounting/valid/accounting.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": "network-radius-accounting/v1alpha1",
+  "eventTimestamp": 1788336000,
+  "statusType": "interim-update",
+  "accountingSessionId": "session-1",
+  "sessionId": "soha-session-1",
+  "nasId": "nas-hq",
+  "nasPortId": "wlan-1",
+  "userId": "user-1",
+  "deviceId": "device-1",
+  "sessionTimeSeconds": 300,
+  "inputOctets": 1024,
+  "outputOctets": 2048,
+  "inputPackets": 10,
+  "outputPackets": 20
+}

package/fixtures/json-schema/network-runtime-protocol/invalid/invalid-cidr.json

@@ -0,0 +1,31 @@
+{
+  "schemaVersion": "network-runtime/v1alpha1",
+  "messageId": "msg-invalid-cidr",
+  "messageType": "configuration.desired",
+  "producerId": "network-control-default",
+  "runtimeId": "gateway-site-a",
+  "runtimeKind": "gateway",
+  "occurredAt": "2026-09-02T08:00:00Z",
+  "expiresAt": "2026-09-02T08:05:00Z",
+  "payload": {
+    "configurationVersion": 12,
+    "policyVersion": 7,
+    "validUntil": "2026-09-02T08:05:00Z",
+    "accessProfile": "full",
+    "protectedResourceIds": [],
+    "networkLeases": [
+      {
+        "id": "network-lease-invalid",
+        "sessionId": "session-0001",
+        "subjectId": "user-alice",
+        "deviceId": "device-alice-laptop",
+        "networkSpaceId": "space-site-a",
+        "cidrs": ["999.999.999.999/999"],
+        "policyVersion": 7,
+        "issuedAt": "2026-09-02T08:00:00Z",
+        "expiresAt": "2026-09-02T08:05:00Z"
+      }
+    ],
+    "resourceLeases": []
+  }
+}

package/fixtures/json-schema/network-runtime-protocol/invalid/message-payload-mismatch.json

@@ -0,0 +1,19 @@
+{
+  "schemaVersion": "network-runtime/v1alpha1",
+  "messageId": "msg-mismatch-0001",
+  "messageType": "lease.revoke",
+  "producerId": "network-control-default",
+  "runtimeId": "gateway-site-a",
+  "runtimeKind": "gateway",
+  "occurredAt": "2026-09-02T08:00:00Z",
+  "expiresAt": "2026-09-02T08:05:00Z",
+  "payload": {
+    "configurationVersion": 12,
+    "policyVersion": 7,
+    "validUntil": "2026-09-02T08:05:00Z",
+    "accessProfile": "full",
+    "protectedResourceIds": [],
+    "networkLeases": [],
+    "resourceLeases": []
+  }
+}

package/fixtures/json-schema/network-runtime-protocol/invalid/mihomo-raw-subscription.json

@@ -0,0 +1,33 @@
+{
+  "schemaVersion": "network-runtime/v1alpha1",
+  "messageId": "msg-config-mihomo-secret",
+  "messageType": "configuration.desired",
+  "producerId": "network-control",
+  "runtimeId": "endpoint-alice",
+  "runtimeKind": "endpoint",
+  "occurredAt": "2026-09-03T08:00:00Z",
+  "expiresAt": "2026-09-03T08:05:00Z",
+  "payload": {
+    "configurationVersion": 13,
+    "policyVersion": 7,
+    "validUntil": "2026-09-03T08:05:00Z",
+    "accessProfile": "full",
+    "protectedResourceIds": [],
+    "networkLeases": [],
+    "resourceLeases": [],
+    "mihomo": {
+      "mode": "managed_follow",
+      "profileId": "profile-corporate-egress",
+      "profileRevision": 4,
+      "mixedPort": 7890,
+      "controllerPort": 9090,
+      "dnsMode": "disabled",
+      "selectorGroup": "SOHA",
+      "selectedProxy": "corporate-hk",
+      "bypassCidrs": [],
+      "bypassHosts": [],
+      "failClosed": true,
+      "subscriptionUrl": "https://secret.example.com/subscription?token=must-not-cross-runtime-contract"
+    }
+  }
+}

package/fixtures/json-schema/network-runtime-protocol/invalid/nas-authorization-password.json

@@ -0,0 +1,18 @@
+{
+  "schemaVersion": "network-runtime/v1alpha1",
+  "messageId": "msg-nas-secret",
+  "messageType": "nas.authorization.request",
+  "producerId": "freeradius-site-a",
+  "runtimeId": "freeradius-site-a",
+  "runtimeKind": "nas",
+  "occurredAt": "2026-09-02T08:00:00Z",
+  "expiresAt": "2026-09-02T08:00:05Z",
+  "payload": {
+    "requestId": "radius-request-secret",
+    "nasId": "nas-site-a-wifi",
+    "subjectId": "user-alice",
+    "deviceId": "device-alice-laptop",
+    "authenticationMethod": "password-compatible",
+    "userPassword": "must-never-cross-the-contract"
+  }
+}

package/fixtures/json-schema/network-runtime-protocol/invalid/nas-eap-without-certificate.json

@@ -0,0 +1,17 @@
+{
+  "schemaVersion": "network-runtime/v1alpha1",
+  "messageId": "msg-nas-eap-without-certificate",
+  "messageType": "nas.authorization.request",
+  "producerId": "freeradius-site-a",
+  "runtimeId": "freeradius-site-a",
+  "runtimeKind": "nas",
+  "occurredAt": "2026-09-02T08:00:00Z",
+  "expiresAt": "2026-09-02T08:00:05Z",
+  "payload": {
+    "requestId": "radius-request-eap-without-certificate",
+    "nasId": "nas-site-a-wifi",
+    "subjectId": "user-alice",
+    "stationId": "AA-BB-CC-DD-EE-FF",
+    "authenticationMethod": "eap-tls"
+  }
+}

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

@@ -0,0 +1,20 @@
+{
+  "schemaVersion": "network-runtime/v1alpha1",
+  "messageId": "msg-config-secret",
+  "messageType": "configuration.desired",
+  "producerId": "network-control-default",
+  "runtimeId": "gateway-site-a",
+  "runtimeKind": "gateway",
+  "occurredAt": "2026-09-02T08:00:00Z",
+  "expiresAt": "2026-09-02T08:05:00Z",
+  "payload": {
+    "configurationVersion": 12,
+    "policyVersion": 7,
+    "validUntil": "2026-09-02T08:05:00Z",
+    "accessProfile": "full",
+    "protectedResourceIds": [],
+    "networkLeases": [],
+    "resourceLeases": [],
+    "wireguardPrivateKey": "must-never-cross-the-contract"
+  }
+}

package/fixtures/json-schema/network-runtime-protocol/invalid/raw-credential-reference.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": "network-runtime/v1alpha1",
+  "messageId": "msg-raw-credential",
+  "messageType": "runtime.enroll.result",
+  "producerId": "network-control-default",
+  "runtimeId": "endpoint-alice-laptop",
+  "runtimeKind": "endpoint",
+  "occurredAt": "2026-09-02T08:00:00Z",
+  "expiresAt": "2026-09-02T08:05:00Z",
+  "payload": {
+    "accepted": true,
+    "reasonCode": "enrolled",
+    "credentialReference": "raw-private-credential-material",
+    "credentialExpiresAt": "2026-09-03T08:00:00Z"
+  }
+}

package/fixtures/json-schema/network-runtime-protocol/invalid/runtime-interval-too-short.json

@@ -0,0 +1,23 @@
+{
+  "schemaVersion": "network-runtime/v1alpha1",
+  "messageId": "msg-config-invalid-interval",
+  "messageType": "configuration.desired",
+  "producerId": "network-control-default",
+  "runtimeId": "endpoint-alice",
+  "runtimeKind": "endpoint",
+  "occurredAt": "2026-09-02T08:00:00Z",
+  "expiresAt": "2026-09-02T08:05:00Z",
+  "payload": {
+    "configurationVersion": 12,
+    "policyVersion": 7,
+    "validUntil": "2026-09-02T08:05:00Z",
+    "accessProfile": "full",
+    "protectedResourceIds": [],
+    "networkLeases": [],
+    "resourceLeases": [],
+    "runtimeIntervals": {
+      "heartbeatIntervalSeconds": 29,
+      "configurationPollIntervalSeconds": 60
+    }
+  }
+}

package/fixtures/json-schema/network-runtime-protocol/invalid/wireguard-capability-without-key.json

@@ -0,0 +1,19 @@
+{
+  "schemaVersion": "network-runtime/v1alpha1",
+  "messageId": "msg-enroll-wireguard-no-key",
+  "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-----",
+    "platform": "windows",
+    "clientVersion": "0.2.0",
+    "capabilities": ["wireguard"]
+  }
+}

package/fixtures/json-schema/network-runtime-protocol/invalid/wireguard-default-route.json

@@ -0,0 +1,31 @@
+{
+  "schemaVersion": "network-runtime/v1alpha1",
+  "messageId": "msg-config-default-route",
+  "messageType": "configuration.desired",
+  "producerId": "network-control",
+  "runtimeId": "endpoint-alice",
+  "runtimeKind": "endpoint",
+  "occurredAt": "2026-09-02T08:00:00Z",
+  "expiresAt": "2026-09-02T08:05:00Z",
+  "payload": {
+    "configurationVersion": 13,
+    "policyVersion": 7,
+    "validUntil": "2026-09-02T08:05:00Z",
+    "accessProfile": "full",
+    "protectedResourceIds": [],
+    "networkLeases": [],
+    "resourceLeases": [],
+    "wireguard": {
+      "role": "endpoint",
+      "interfaceName": "soha0",
+      "publicKey": "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=",
+      "addresses": ["100.96.10.2/32"],
+      "mtu": 1380,
+      "routingMode": "routed",
+      "firewallDefault": "deny",
+      "peers": [],
+      "routes": ["0.0.0.0/0"],
+      "firewallRules": []
+    }
+  }
+}

package/fixtures/json-schema/network-runtime-protocol/invalid/ztna-without-access-grant.json

@@ -0,0 +1,17 @@
+{
+  "schemaVersion": "network-runtime/v1alpha1",
+  "messageId": "msg-invalid-ztna-grant",
+  "messageType": "vpn.connect.request",
+  "producerId": "endpoint-1",
+  "runtimeId": "endpoint-1",
+  "runtimeKind": "endpoint",
+  "occurredAt": "2026-09-03T08:00:00Z",
+  "expiresAt": "2026-09-03T08:01:00Z",
+  "payload": {
+    "requestId": "request-invalid-ztna",
+    "siteId": "site-hq",
+    "networkSpaceId": "space-corp",
+    "mode": "external_vpn_ztna",
+    "resourceIds": ["resource-payroll"]
+  }
+}

package/fixtures/json-schema/network-runtime-protocol/valid/configuration-desired.json

@@ -0,0 +1,86 @@
+{
+  "schemaVersion": "network-runtime/v1alpha1",
+  "messageId": "msg-config-0001",
+  "messageType": "configuration.desired",
+  "producerId": "network-control-default",
+  "runtimeId": "gateway-site-a",
+  "runtimeKind": "gateway",
+  "occurredAt": "2026-09-02T08:00:00Z",
+  "expiresAt": "2026-09-02T08:05:00Z",
+  "payload": {
+    "configurationVersion": 12,
+    "policyVersion": 7,
+    "validUntil": "2026-09-02T08:05:00Z",
+    "accessProfile": "full",
+    "protectedResourceIds": ["resource-payroll"],
+    "networkLeases": [
+      {
+        "id": "network-lease-0001",
+        "sessionId": "session-0001",
+        "subjectId": "user-alice",
+        "deviceId": "device-alice-laptop",
+        "networkSpaceId": "space-site-a",
+        "cidrs": ["10.20.0.0/16"],
+        "policyVersion": 7,
+        "issuedAt": "2026-09-02T08:00:00Z",
+        "expiresAt": "2026-09-02T08:05:00Z"
+      }
+    ],
+    "resourceLeases": [
+      {
+        "id": "resource-lease-0001",
+        "sessionId": "session-0001",
+        "subjectId": "user-alice",
+        "deviceId": "device-alice-laptop",
+        "resourceIds": ["resource-payroll"],
+        "policyVersion": 7,
+        "issuedAt": "2026-09-02T08:00:00Z",
+        "expiresAt": "2026-09-02T08:02:00Z"
+      }
+    ],
+    "runtimeIntervals": {
+      "heartbeatIntervalSeconds": 60,
+      "configurationPollIntervalSeconds": 60
+    },
+    "wireguard": {
+      "role": "gateway",
+      "interfaceName": "soha0",
+      "publicKey": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",
+      "addresses": ["100.96.10.1/32"],
+      "listenPort": 51820,
+      "mtu": 1380,
+      "routingMode": "routed",
+      "firewallDefault": "deny",
+      "peers": [
+        {
+          "runtimeId": "endpoint-alice",
+          "deviceId": "device-alice-laptop",
+          "publicKey": "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=",
+          "allowedIPs": ["100.96.10.2/32"],
+          "persistentKeepaliveSeconds": 25
+        }
+      ],
+      "routes": ["10.20.0.0/16"],
+      "dnsServers": ["10.20.0.53"],
+      "firewallRules": [
+        {
+          "id": "deny-payroll",
+          "effect": "deny",
+          "sourceCidr": "100.96.10.2/32",
+          "destinationCidr": "10.20.8.10/32",
+          "protocol": "tcp",
+          "ports": [443]
+        },
+        {
+          "id": "allow-network-lease-0001",
+          "effect": "allow",
+          "leaseId": "network-lease-0001",
+          "sourceCidr": "100.96.10.2/32",
+          "destinationCidr": "10.20.0.0/16",
+          "protocol": "any",
+          "expiresAt": "2026-09-02T08:05:00Z"
+        }
+      ]
+    }
+  }
+}

package/fixtures/json-schema/network-runtime-protocol/valid/direct-ztna-connect.json

@@ -0,0 +1,19 @@
+{
+  "schemaVersion": "network-runtime/v1alpha1",
+  "messageId": "msg-direct-ztna-connect-0001",
+  "messageType": "vpn.connect.request",
+  "producerId": "endpoint-alice",
+  "runtimeId": "endpoint-alice",
+  "runtimeKind": "endpoint",
+  "occurredAt": "2026-09-02T08:00:00Z",
+  "expiresAt": "2026-09-02T08:05:00Z",
+  "payload": {
+    "requestId": "direct-ztna-request-0001",
+    "siteId": "site-a",
+    "networkSpaceId": "space-site-a",
+    "mode": "external_direct_ztna",
+    "resourceIds": ["resource-payroll"],
+    "accessGrantId": "grant-payroll",
+    "accessGrantToken": "hJ0iZcfcPK5E0lKo9C4NsMdy2r2V1B9DUFKkphz-g8I"
+  }
+}