@opensoha/contracts 0.1.20 → 0.1.21

package/network/network-runtime-protocol.schema.json

@@ -42,7 +42,7 @@
     },
     "producerId": { "$ref": "#/$defs/Identifier" },
     "runtimeId": { "$ref": "#/$defs/Identifier" },
-    "runtimeKind": { "enum": ["endpoint", "gateway", "nas"] },
+    "runtimeKind": { "enum": ["endpoint", "gateway", "nas", "proxy"] },
     "occurredAt": { "type": "string", "format": "date-time" },
     "expiresAt": { "type": "string", "format": "date-time" },
     "payload": {
@@ -712,7 +712,7 @@
           "minItems": 1,
           "maxItems": 32,
           "uniqueItems": true,
-          "items": { "enum": ["wireguard", "mihomo", "route-coordinator", "dns-coordinator", "managed-vpn-v1", "vpn-probe-v1", "vpn-metrics-v1"] }
+          "items": { "enum": ["wireguard", "mihomo", "route-coordinator", "dns-coordinator", "managed-vpn-v1", "vpn-probe-v1", "vpn-metrics-v1", "proxy-runtime-v1"] }
         }
       },
       "allOf": [{

package/network/proxy-runtime.schema.json

@@ -0,0 +1,113 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.opensoha.dev/network/proxy-runtime.schema.json",
+  "title": "OpenSoha Proxy Runtime Message",
+  "description": "Messages on the authenticated proxy runtime channel. Configuration content is delivered only to the enrolled runtime and is never returned by management reads.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "runtimeId", "messageType", "occurredAt", "payload"],
+  "properties": {
+    "schemaVersion": { "const": "proxy-runtime/v1alpha1" },
+    "runtimeId": { "$ref": "#/$defs/Identifier" },
+    "messageType": { "enum": ["configuration.desired", "configuration.applied", "observation", "connections.snapshot", "connection.close.request", "connection.close.result"] },
+    "occurredAt": { "type": "string", "format": "date-time" },
+    "payload": {
+      "oneOf": [
+        { "$ref": "#/$defs/ConfigurationDesired" },
+        { "$ref": "#/$defs/ConfigurationApplied" },
+        { "$ref": "#/$defs/Observation" },
+        { "$ref": "#/$defs/ConnectionsSnapshot" },
+        { "$ref": "#/$defs/ConnectionCloseRequest" },
+        { "$ref": "#/$defs/ConnectionCloseResult" }
+      ]
+    }
+  },
+  "allOf": [
+    { "if": { "properties": { "messageType": { "const": "configuration.desired" } }, "required": ["messageType"] }, "then": { "properties": { "payload": { "$ref": "#/$defs/ConfigurationDesired" } } } },
+    { "if": { "properties": { "messageType": { "const": "configuration.applied" } }, "required": ["messageType"] }, "then": { "properties": { "payload": { "$ref": "#/$defs/ConfigurationApplied" } } } },
+    { "if": { "properties": { "messageType": { "const": "observation" } }, "required": ["messageType"] }, "then": { "properties": { "payload": { "$ref": "#/$defs/Observation" } } } },
+    { "if": { "properties": { "messageType": { "const": "connections.snapshot" } }, "required": ["messageType"] }, "then": { "properties": { "payload": { "$ref": "#/$defs/ConnectionsSnapshot" } } } },
+    { "if": { "properties": { "messageType": { "const": "connection.close.request" } }, "required": ["messageType"] }, "then": { "properties": { "payload": { "$ref": "#/$defs/ConnectionCloseRequest" } } } },
+    { "if": { "properties": { "messageType": { "const": "connection.close.result" } }, "required": ["messageType"] }, "then": { "properties": { "payload": { "$ref": "#/$defs/ConnectionCloseResult" } } } }
+  ],
+  "$defs": {
+    "Identifier": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" },
+    "Engine": { "enum": ["mihomo", "sing-box", "v2ray"] },
+    "Hash": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "ConfigurationDesired": {
+      "type": "object", "additionalProperties": false,
+      "required": ["revision", "engine", "enabled", "contentHash", "content", "validUntil"],
+      "properties": {
+        "revision": { "type": "integer", "minimum": 1 },
+        "engine": { "$ref": "#/$defs/Engine" },
+        "enabled": { "type": "boolean" },
+        "contentHash": { "$ref": "#/$defs/Hash" },
+        "content": { "type": "string", "minLength": 1, "maxLength": 1048576, "writeOnly": true },
+        "validUntil": { "type": "string", "format": "date-time" }
+      }
+    },
+    "ConfigurationApplied": {
+      "type": "object", "additionalProperties": false,
+      "required": ["revision", "status", "readbackHash"],
+      "properties": {
+        "revision": { "type": "integer", "minimum": 1 },
+        "status": { "enum": ["applied", "rejected", "rolled-back"] },
+        "readbackHash": { "$ref": "#/$defs/Hash" },
+        "reasonCode": { "type": "string", "minLength": 1, "maxLength": 128 }
+      }
+    },
+    "Observation": {
+      "type": "object", "additionalProperties": false,
+      "required": ["engine", "engineVersion", "health", "capabilities", "uptimeSeconds", "uploadTotal", "downloadTotal"],
+      "properties": {
+        "engine": { "$ref": "#/$defs/Engine" },
+        "engineVersion": { "type": "string", "minLength": 1, "maxLength": 64 },
+        "health": { "enum": ["healthy", "degraded", "unhealthy"] },
+        "capabilities": { "type": "array", "maxItems": 3, "uniqueItems": true, "items": { "enum": ["traffic", "connections", "close_connection"] } },
+        "reasonCode": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "uptimeSeconds": { "type": "integer", "minimum": 0 },
+        "uploadTotal": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 },
+        "downloadTotal": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 },
+        "activeConnections": { "type": "integer", "minimum": 0, "maximum": 1000000 }
+      }
+    },
+    "Connection": {
+      "type": "object", "additionalProperties": false,
+      "required": ["id", "destination", "network", "uploadBytes", "downloadBytes"],
+      "properties": {
+        "id": { "$ref": "#/$defs/Identifier" },
+        "destination": { "type": "string", "minLength": 1, "maxLength": 253 },
+        "network": { "enum": ["tcp", "udp", "other"] },
+        "uploadBytes": { "type": "integer", "minimum": 0 },
+        "downloadBytes": { "type": "integer", "minimum": 0 },
+        "startedAt": { "type": "string", "format": "date-time" }
+      }
+    },
+    "ConnectionsSnapshot": {
+      "type": "object", "additionalProperties": false,
+      "required": ["engine", "connections"],
+      "properties": {
+        "engine": { "enum": ["mihomo", "sing-box"] },
+        "connections": { "type": "array", "maxItems": 200, "items": { "$ref": "#/$defs/Connection" } }
+      }
+    },
+    "ConnectionCloseRequest": {
+      "type": "object", "additionalProperties": false,
+      "required": ["commandId", "connectionId", "expiresAt"],
+      "properties": {
+        "commandId": { "$ref": "#/$defs/Identifier" },
+        "connectionId": { "$ref": "#/$defs/Identifier" },
+        "expiresAt": { "type": "string", "format": "date-time" }
+      }
+    },
+    "ConnectionCloseResult": {
+      "type": "object", "additionalProperties": false,
+      "required": ["commandId", "status"],
+      "properties": {
+        "commandId": { "$ref": "#/$defs/Identifier" },
+        "status": { "enum": ["closed", "not-found", "failed"] },
+        "reasonCode": { "type": "string", "minLength": 1, "maxLength": 128 }
+      }
+    }
+  }
+}

package/network/schema.go

@@ -11,6 +11,9 @@ var (
 
 	//go:embed network-radius-accounting.schema.json
 	radiusAccountingSchema []byte
+
+	//go:embed proxy-runtime.schema.json
+	proxyRuntimeSchema []byte
 )
 
 func RuntimeProtocolSchema() []byte {
@@ -24,3 +27,7 @@ func IngestEventSchema() []byte {
 func RadiusAccountingSchema() []byte {
 	return append([]byte(nil), radiusAccountingSchema...)
 }
+
+func ProxyRuntimeSchema() []byte {
+	return append([]byte(nil), proxyRuntimeSchema...)
+}

package/openapi/soha-api.json

@@ -24933,7 +24933,14 @@
                 "update",
                 "delete"
               ],
-              "type": "string"
+              "type": "string",
+              "x-enum-varnames": [
+                "CustomResourceAccessList",
+                "CustomResourceAccessView",
+                "CustomResourceAccessCreate",
+                "CustomResourceAccessUpdate",
+                "CustomResourceAccessDelete"
+              ]
             },
             "type": "array"
           }
@@ -24972,6 +24979,10 @@
           "createdAt": {
             "type": "string"
           },
+          "deletingAt": {
+            "format": "date-time",
+            "type": "string"
+          },
           "group": {
             "type": "string"
           },
@@ -24987,6 +24998,11 @@
           "scope": {
             "type": "string"
           },
+          "uid": {
+            "maxLength": 128,
+            "minLength": 1,
+            "type": "string"
+          },
           "version": {
             "type": "string"
           },
@@ -41707,6 +41723,173 @@
         ],
         "type": "object"
       },
+      "NetworkProxyCapability": {
+        "enum": [
+          "traffic",
+          "connections",
+          "close_connection"
+        ],
+        "type": "string",
+        "x-enum-varnames": [
+          "NetworkProxyCapabilityTraffic",
+          "NetworkProxyCapabilityConnections",
+          "NetworkProxyCapabilityCloseConnection"
+        ]
+      },
+      "NetworkProxyCloseCommandEnvelope": {
+        "additionalProperties": false,
+        "properties": {
+          "commandId": {
+            "maxLength": 128,
+            "minLength": 1,
+            "type": "string"
+          },
+          "expiresAt": {
+            "format": "date-time",
+            "type": "string"
+          },
+          "status": {
+            "enum": [
+              "pending",
+              "closed",
+              "not-found",
+              "failed",
+              "expired"
+            ],
+            "type": "string"
+          }
+        },
+        "required": [
+          "commandId",
+          "status",
+          "expiresAt"
+        ],
+        "type": "object"
+      },
+      "NetworkProxyConfigurationInput": {
+        "additionalProperties": false,
+        "properties": {
+          "content": {
+            "format": "password",
+            "maxLength": 1048576,
+            "minLength": 1,
+            "type": "string",
+            "writeOnly": true
+          },
+          "enabled": {
+            "type": "boolean"
+          },
+          "expectedRevision": {
+            "format": "int64",
+            "minimum": 0,
+            "type": "integer"
+          }
+        },
+        "required": [
+          "expectedRevision",
+          "enabled",
+          "content"
+        ],
+        "type": "object"
+      },
+      "NetworkProxyConnection": {
+        "additionalProperties": false,
+        "properties": {
+          "destination": {
+            "maxLength": 253,
+            "minLength": 1,
+            "type": "string"
+          },
+          "downloadBytes": {
+            "format": "int64",
+            "minimum": 0,
+            "type": "integer"
+          },
+          "id": {
+            "maxLength": 128,
+            "minLength": 1,
+            "type": "string"
+          },
+          "network": {
+            "enum": [
+              "tcp",
+              "udp",
+              "other"
+            ],
+            "type": "string",
+            "x-enum-varnames": [
+              "NetworkProxyConnectionNetworkTCP",
+              "NetworkProxyConnectionNetworkUDP",
+              "NetworkProxyConnectionNetworkOther"
+            ]
+          },
+          "startedAt": {
+            "format": "date-time",
+            "type": "string"
+          },
+          "uploadBytes": {
+            "format": "int64",
+            "minimum": 0,
+            "type": "integer"
+          }
+        },
+        "required": [
+          "id",
+          "destination",
+          "network",
+          "uploadBytes",
+          "downloadBytes"
+        ],
+        "type": "object"
+      },
+      "NetworkProxyConnectionsEnvelope": {
+        "additionalProperties": false,
+        "properties": {
+          "connections": {
+            "items": {
+              "$ref": "#/components/schemas/NetworkProxyConnection"
+            },
+            "maxItems": 200,
+            "type": "array"
+          },
+          "instanceId": {
+            "maxLength": 128,
+            "minLength": 1,
+            "type": "string"
+          },
+          "observedAt": {
+            "format": "date-time",
+            "type": "string"
+          },
+          "state": {
+            "enum": [
+              "available",
+              "unsupported",
+              "unavailable"
+            ],
+            "type": "string"
+          }
+        },
+        "required": [
+          "instanceId",
+          "state",
+          "connections"
+        ],
+        "type": "object"
+      },
+      "NetworkProxyEngine": {
+        "enum": [
+          "mihomo",
+          "sing-box",
+          "v2ray"
+        ],
+        "type": "string",
+        "x-enum-varnames": [
+          "NetworkProxyEngineMihomo",
+          "NetworkProxyEngineSingBox",
+          "NetworkProxyEngineV2Ray"
+        ]
+      },
       "NetworkProxyFlowSummary": {
         "additionalProperties": false,
         "properties": {
@@ -41770,6 +41953,228 @@
         ],
         "type": "object"
       },
+      "NetworkProxyInstance": {
+        "additionalProperties": false,
+        "properties": {
+          "capabilities": {
+            "items": {
+              "$ref": "#/components/schemas/NetworkProxyCapability"
+            },
+            "maxItems": 3,
+            "type": "array",
+            "uniqueItems": true
+          },
+          "createdAt": {
+            "format": "date-time",
+            "type": "string"
+          },
+          "desiredRevision": {
+            "format": "int64",
+            "minimum": 0,
+            "type": "integer"
+          },
+          "enabled": {
+            "type": "boolean"
+          },
+          "engine": {
+            "$ref": "#/components/schemas/NetworkProxyEngine"
+          },
+          "engineVersion": {
+            "maxLength": 64,
+            "type": "string"
+          },
+          "host": {
+            "maxLength": 128,
+            "type": "string"
+          },
+          "id": {
+            "maxLength": 128,
+            "minLength": 1,
+            "type": "string"
+          },
+          "lastSampleAt": {
+            "format": "date-time",
+            "type": "string"
+          },
+          "lastSeenAt": {
+            "format": "date-time",
+            "type": "string"
+          },
+          "name": {
+            "maxLength": 128,
+            "minLength": 1,
+            "type": "string"
+          },
+          "observedRevision": {
+            "format": "int64",
+            "minimum": 0,
+            "type": "integer"
+          },
+          "reasonCode": {
+            "maxLength": 128,
+            "type": "string"
+          },
+          "status": {
+            "$ref": "#/components/schemas/NetworkProxyInstanceStatus"
+          },
+          "updatedAt": {
+            "format": "date-time",
+            "type": "string"
+          }
+        },
+        "required": [
+          "id",
+          "name",
+          "engine",
+          "enabled",
+          "status",
+          "capabilities",
+          "desiredRevision",
+          "observedRevision",
+          "createdAt",
+          "updatedAt"
+        ],
+        "type": "object"
+      },
+      "NetworkProxyInstanceEnvelope": {
+        "additionalProperties": false,
+        "properties": {
+          "data": {
+            "$ref": "#/components/schemas/NetworkProxyInstance"
+          }
+        },
+        "required": [
+          "data"
+        ],
+        "type": "object"
+      },
+      "NetworkProxyInstanceInput": {
+        "additionalProperties": false,
+        "properties": {
+          "engine": {
+            "$ref": "#/components/schemas/NetworkProxyEngine"
+          },
+          "host": {
+            "maxLength": 128,
+            "type": "string"
+          },
+          "id": {
+            "maxLength": 128,
+            "minLength": 1,
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$",
+            "type": "string"
+          },
+          "name": {
+            "maxLength": 128,
+            "minLength": 1,
+            "type": "string"
+          }
+        },
+        "required": [
+          "id",
+          "name",
+          "engine"
+        ],
+        "type": "object"
+      },
+      "NetworkProxyInstanceListEnvelope": {
+        "additionalProperties": false,
+        "properties": {
+          "items": {
+            "items": {
+              "$ref": "#/components/schemas/NetworkProxyInstance"
+            },
+            "maxItems": 200,
+            "type": "array"
+          }
+        },
+        "required": [
+          "items"
+        ],
+        "type": "object"
+      },
+      "NetworkProxyInstanceStatus": {
+        "enum": [
+          "unregistered",
+          "online",
+          "degraded",
+          "offline",
+          "disabled"
+        ],
+        "type": "string",
+        "x-enum-varnames": [
+          "NetworkProxyInstanceStatusUnregistered",
+          "NetworkProxyInstanceStatusOnline",
+          "NetworkProxyInstanceStatusDegraded",
+          "NetworkProxyInstanceStatusOffline",
+          "NetworkProxyInstanceStatusDisabled"
+        ]
+      },
+      "NetworkProxyTrafficEnvelope": {
+        "additionalProperties": false,
+        "properties": {
+          "instanceId": {
+            "maxLength": 128,
+            "minLength": 1,
+            "type": "string"
+          },
+          "samples": {
+            "items": {
+              "$ref": "#/components/schemas/NetworkProxyTrafficSample"
+            },
+            "maxItems": 1440,
+            "type": "array"
+          },
+          "supported": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "instanceId",
+          "supported",
+          "samples"
+        ],
+        "type": "object"
+      },
+      "NetworkProxyTrafficSample": {
+        "additionalProperties": false,
+        "properties": {
+          "activeConnections": {
+            "minimum": 0,
+            "type": "integer"
+          },
+          "downloadBytesPerSecond": {
+            "minimum": 0,
+            "type": "number"
+          },
+          "downloadTotal": {
+            "format": "int64",
+            "minimum": 0,
+            "type": "integer"
+          },
+          "observedAt": {
+            "format": "date-time",
+            "type": "string"
+          },
+          "uploadBytesPerSecond": {
+            "minimum": 0,
+            "type": "number"
+          },
+          "uploadTotal": {
+            "format": "int64",
+            "minimum": 0,
+            "type": "integer"
+          }
+        },
+        "required": [
+          "observedAt",
+          "uploadTotal",
+          "downloadTotal",
+          "uploadBytesPerSecond",
+          "downloadBytesPerSecond"
+        ],
+        "type": "object"
+      },
       "NetworkResource": {
         "additionalProperties": false,
         "properties": {
@@ -42030,6 +42435,7 @@
       },
       "NetworkRuntimeEnrollmentInput": {
         "additionalProperties": false,
+        "description": "For proxy runtimes, runtimeId identifies an existing proxy instance and deviceId and subjectId must equal runtimeId.",
         "properties": {
           "deviceId": {
             "maxLength": 128,
@@ -42129,13 +42535,15 @@
         "enum": [
           "endpoint",
           "gateway",
-          "nas"
+          "nas",
+          "proxy"
         ],
         "type": "string",
         "x-enum-varnames": [
           "NetworkRuntimeKindEndpoint",
           "NetworkRuntimeKindGateway",
-          "NetworkRuntimeKindNAS"
+          "NetworkRuntimeKindNAS",
+          "NetworkRuntimeKindProxy"
         ]
       },
       "NetworkSession": {
@@ -61322,7 +61730,7 @@
   "info": {
     "description": "Public OpenSoha core API contract. This first contract focuses on stable cross-repository boundaries: auth, health, runner-facing control-plane callbacks, AI Gateway, and MCP capability discovery.\n",
     "title": "Soha API",
-    "version": "0.1.20"
+    "version": "0.1.21"
   },
   "openapi": "3.1.0",
   "paths": {