@opensoha/contracts 0.1.25 → 0.1.27

package/network/proxy-runtime.schema.json

@@ -5,109 +5,524 @@
   "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"],
+  "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" },
+    "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" }
+        {
+          "$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" } } } }
+    {
+      "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}$" },
+    "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"],
+      "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" }
+        "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"
+        },
+        "binding": {
+          "$ref": "#/$defs/Binding"
+        },
+        "protection": {
+          "$ref": "#/$defs/Protection"
+        }
       }
     },
     "ConfigurationApplied": {
-      "type": "object", "additionalProperties": false,
-      "required": ["revision", "status", "readbackHash"],
+      "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 }
+        "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"],
+      "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 }
+        "engine": {
+          "$ref": "#/$defs/Engine"
+        },
+        "engineVersion": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64
+        },
+        "health": {
+          "enum": [
+            "healthy",
+            "degraded",
+            "unhealthy"
+          ]
+        },
+        "capabilities": {
+          "type": "array",
+          "maxItems": 6,
+          "uniqueItems": true,
+          "items": {
+            "enum": [
+              "traffic",
+              "connections",
+              "close_connection",
+              "protected_destinations_v1",
+              "protection_rules_readback",
+              "guarded_dns_tcp_v1"
+            ]
+          }
+        },
+        "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"],
+      "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" }
+        "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"],
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "engine",
+        "connections"
+      ],
       "properties": {
-        "engine": { "enum": ["mihomo", "sing-box"] },
-        "connections": { "type": "array", "maxItems": 200, "items": { "$ref": "#/$defs/Connection" } }
+        "engine": {
+          "enum": [
+            "mihomo",
+            "sing-box"
+          ]
+        },
+        "connections": {
+          "type": "array",
+          "maxItems": 200,
+          "items": {
+            "$ref": "#/$defs/Connection"
+          }
+        }
       }
     },
     "ConnectionCloseRequest": {
-      "type": "object", "additionalProperties": false,
-      "required": ["commandId", "connectionId", "expiresAt"],
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "commandId",
+        "connectionId",
+        "expiresAt"
+      ],
       "properties": {
-        "commandId": { "$ref": "#/$defs/Identifier" },
-        "connectionId": { "$ref": "#/$defs/Identifier" },
-        "expiresAt": { "type": "string", "format": "date-time" }
+        "commandId": {
+          "$ref": "#/$defs/Identifier"
+        },
+        "connectionId": {
+          "$ref": "#/$defs/Identifier"
+        },
+        "expiresAt": {
+          "type": "string",
+          "format": "date-time"
+        }
       }
     },
     "ConnectionCloseResult": {
-      "type": "object", "additionalProperties": false,
-      "required": ["commandId", "status"],
+      "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 }
+        "commandId": {
+          "$ref": "#/$defs/Identifier"
+        },
+        "status": {
+          "enum": [
+            "closed",
+            "not-found",
+            "failed"
+          ]
+        },
+        "reasonCode": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128
+        }
       }
+    },
+    "Binding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "siteId",
+        "deviceId",
+        "resourceIds"
+      ],
+      "properties": {
+        "siteId": {
+          "$ref": "#/$defs/Identifier"
+        },
+        "deviceId": {
+          "$ref": "#/$defs/Identifier"
+        },
+        "resourceIds": {
+          "type": "array",
+          "maxItems": 128,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/Identifier"
+          }
+        }
+      }
+    },
+    "Protection": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "policyVersion",
+        "cidrs",
+        "hosts"
+      ],
+      "properties": {
+        "policyVersion": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "cidrs": {
+          "type": "array",
+          "maxItems": 4096,
+          "uniqueItems": true,
+          "items": {
+            "allOf": [
+              {
+                "$ref": "#/$defs/IPCIDR"
+              },
+              {
+                "not": {
+                  "enum": [
+                    "0.0.0.0/0",
+                    "::/0"
+                  ]
+                }
+              }
+            ]
+          }
+        },
+        "hosts": {
+          "type": "array",
+          "maxItems": 2048,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 253,
+            "pattern": "^(?:[A-Za-z0-9](?:[A-Za-z0-9.-]{0,251}[A-Za-z0-9])?|[A-Za-z0-9])$"
+          }
+        }
+      }
+    },
+    "IPv4CIDR": {
+      "type": "string",
+      "maxLength": 18,
+      "pattern": "^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])/(?:[0-9]|[12][0-9]|3[0-2])$",
+      "description": "Canonical IPv4 CIDR; use IPCIDR for either supported address family."
+    },
+    "IPCIDR": {
+      "type": "string",
+      "maxLength": 64,
+      "pattern": "^(?:(?:(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])/(?:[1-9]|[12][0-9]|3[0-2])|(?:(?:(?:0|[1-9a-f][0-9a-f]{0,3}):){7}(?:0|[1-9a-f][0-9a-f]{0,3})|(?:(?:0|[1-9a-f][0-9a-f]{0,3}):){1,7}:|(?:(?:0|[1-9a-f][0-9a-f]{0,3}):){1,6}:(?:0|[1-9a-f][0-9a-f]{0,3})|(?:(?:0|[1-9a-f][0-9a-f]{0,3}):){1,5}(?::(?:0|[1-9a-f][0-9a-f]{0,3})){1,2}|(?:(?:0|[1-9a-f][0-9a-f]{0,3}):){1,4}(?::(?:0|[1-9a-f][0-9a-f]{0,3})){1,3}|(?:(?:0|[1-9a-f][0-9a-f]{0,3}):){1,3}(?::(?:0|[1-9a-f][0-9a-f]{0,3})){1,4}|(?:(?:0|[1-9a-f][0-9a-f]{0,3}):){1,2}(?::(?:0|[1-9a-f][0-9a-f]{0,3})){1,5}|(?:0|[1-9a-f][0-9a-f]{0,3}):(?:(?::(?:0|[1-9a-f][0-9a-f]{0,3})){1,6})|:(?:(?::(?:0|[1-9a-f][0-9a-f]{0,3})){1,7}|:))/(?:[1-9]|[1-9][0-9]|1[01][0-9]|12[0-8]))$",
+      "description": "Non-default IPv4 or IPv6 CIDR syntax. Core additionally validates canonical network-address bits and compressed address spelling with netip."
     }
   }
 }

package/openapi/network_control_test.go

@@ -0,0 +1,64 @@
+package openapi
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+func TestEndpointChannelControlTransport(t *testing.T) {
+	type server struct {
+		URL string `json:"url"`
+	}
+	type operation struct {
+		Servers  []server              `json:"servers"`
+		Security []map[string][]string `json:"security"`
+	}
+	var document struct {
+		Servers []server `json:"servers"`
+		Paths   map[string]struct {
+			Servers []server  `json:"servers"`
+			Get     operation `json:"get"`
+			Post    operation `json:"post"`
+		} `json:"paths"`
+		Components struct {
+			SecuritySchemes map[string]struct {
+				Type string `json:"type"`
+			} `json:"securitySchemes"`
+		} `json:"components"`
+	}
+	if err := json.Unmarshal(JSON(), &document); err != nil {
+		t.Fatal(err)
+	}
+	for _, suffix := range []string{"", "/receipt"} {
+		path := "/network-control/v1/runtimes/{runtimeID}/channel-controls" + suffix
+		t.Run(path, func(t *testing.T) {
+			item, ok := document.Paths[path]
+			if !ok {
+				t.Fatal("missing runtime channel control operation")
+			}
+			op := item.Get
+			if suffix != "" {
+				op = item.Post
+			}
+			servers := op.Servers
+			if len(servers) == 0 {
+				servers = item.Servers
+			}
+			if len(servers) == 0 {
+				servers = document.Servers
+			}
+			if len(servers) != 1 || strings.TrimSuffix(servers[0].URL, "/")+path != "/api"+path {
+				t.Errorf("effective server %v does not target the independent /api/network-control/v1 listener", servers)
+			}
+			if len(op.Security) != 1 || len(op.Security[0]) != 1 {
+				t.Fatal("runtime operations must explicitly require one certificate scheme, without a Bearer alternative")
+			}
+			for name, scopes := range op.Security[0] {
+				if len(scopes) != 0 || document.Components.SecuritySchemes[name].Type != "mutualTLS" {
+					t.Errorf("runtime operation requires %q, want a mutualTLS security scheme", name)
+				}
+			}
+		})
+	}
+}