@opensoha/contracts 0.1.17 → 0.1.19

package/mcp/gateway-manifest.schema.json

@@ -15,32 +15,61 @@
     "summary"
   ],
   "properties": {
-    "name": { "type": "string" },
-    "version": { "type": "string" },
-    "generatedAt": { "type": "string", "format": "date-time" },
-    "principal": { "$ref": "#/$defs/Principal" },
-    "caller": { "$ref": "#/$defs/CallerContext" },
+    "name": {
+      "type": "string"
+    },
+    "version": {
+      "type": "string"
+    },
+    "generatedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "principal": {
+      "$ref": "#/$defs/Principal"
+    },
+    "caller": {
+      "$ref": "#/$defs/CallerContext"
+    },
     "permissionKeys": {
       "type": "array",
-      "items": { "type": "string" }
+      "items": {
+        "type": "string"
+      }
     },
     "tools": {
       "type": "array",
-      "items": { "$ref": "#/$defs/ToolCapability" }
+      "items": {
+        "$ref": "#/$defs/ToolCapability"
+      }
     },
     "resources": {
       "type": "array",
-      "items": { "$ref": "#/$defs/ResourceCapability" }
+      "items": {
+        "$ref": "#/$defs/ResourceCapability"
+      }
     },
     "prompts": {
       "type": "array",
-      "items": { "$ref": "#/$defs/PromptCapability" }
+      "items": {
+        "$ref": "#/$defs/PromptCapability"
+      }
     },
     "skills": {
       "type": "array",
-      "items": { "$ref": "#/$defs/SkillCapability" }
+      "items": {
+        "$ref": "#/$defs/SkillCapability"
+      }
+    },
+    "summary": {
+      "$ref": "#/$defs/ManifestSummary"
     },
-    "summary": { "$ref": "#/$defs/ManifestSummary" }
+    "catalogRevision": {
+      "type": "string"
+    },
+    "nextCursor": {
+      "type": "string"
+    }
   },
   "additionalProperties": false,
   "$defs": {
@@ -50,53 +79,103 @@
     },
     "Principal": {
       "type": "object",
-      "required": ["userId", "userName", "email", "roles", "teams", "projects", "tags"],
+      "required": [
+        "userId",
+        "userName",
+        "email",
+        "roles",
+        "teams",
+        "projects",
+        "tags"
+      ],
       "properties": {
-        "userId": { "type": "string" },
-        "userName": { "type": "string" },
-        "email": { "type": "string" },
+        "userId": {
+          "type": "string"
+        },
+        "userName": {
+          "type": "string"
+        },
+        "email": {
+          "type": "string"
+        },
         "roles": {
           "type": "array",
-          "items": { "type": "string" }
+          "items": {
+            "type": "string"
+          }
         },
         "teams": {
           "type": "array",
-          "items": { "type": "string" }
+          "items": {
+            "type": "string"
+          }
         },
         "projects": {
           "type": "array",
-          "items": { "type": "string" }
+          "items": {
+            "type": "string"
+          }
         },
         "tags": {
           "type": "array",
-          "items": { "type": "string" }
+          "items": {
+            "type": "string"
+          }
         },
         "permissionKeys": {
           "type": "array",
-          "items": { "type": "string" }
+          "items": {
+            "type": "string"
+          }
         }
       },
       "additionalProperties": true
     },
     "CallerContext": {
       "type": "object",
-      "required": ["identityMode"],
+      "required": [
+        "identityMode"
+      ],
       "properties": {
-        "identityMode": { "type": "string" },
-        "aiClientId": { "type": "string" },
-        "aiClientName": { "type": "string" },
-        "skillId": { "type": "string" },
-        "tokenId": { "type": "string" },
-        "sessionId": { "type": "string" },
-        "subjectType": { "type": "string" },
-        "subjectId": { "type": "string" },
-        "source": { "type": "string" }
+        "identityMode": {
+          "type": "string"
+        },
+        "aiClientId": {
+          "type": "string"
+        },
+        "aiClientName": {
+          "type": "string"
+        },
+        "skillId": {
+          "type": "string"
+        },
+        "tokenId": {
+          "type": "string"
+        },
+        "sessionId": {
+          "type": "string"
+        },
+        "subjectType": {
+          "type": "string"
+        },
+        "subjectId": {
+          "type": "string"
+        },
+        "source": {
+          "type": "string"
+        }
       },
       "additionalProperties": false
     },
     "RiskLevel": {
       "type": "string",
-      "enum": ["read", "analyze", "mutate", "execute", "high"]
+      "enum": [
+        "read",
+        "analyze",
+        "mutate",
+        "execute",
+        "high"
+      ]
     },
     "ToolCapability": {
       "type": "object",
@@ -111,100 +190,336 @@
         "requiresApproval"
       ],
       "properties": {
-        "name": { "type": "string" },
-        "title": { "type": "string" },
-        "description": { "type": "string" },
-        "domain": { "type": "string" },
-        "action": { "type": "string" },
-        "riskLevel": { "$ref": "#/$defs/RiskLevel" },
+        "name": {
+          "type": "string"
+        },
+        "title": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        },
+        "domain": {
+          "type": "string"
+        },
+        "action": {
+          "type": "string"
+        },
+        "riskLevel": {
+          "$ref": "#/$defs/RiskLevel"
+        },
         "permissionKeys": {
           "type": "array",
-          "items": { "type": "string" }
+          "items": {
+            "type": "string"
+          }
         },
         "requiredScopes": {
           "type": "array",
-          "items": { "type": "string" }
+          "items": {
+            "type": "string"
+          }
+        },
+        "mcpAdapterId": {
+          "type": "string"
+        },
+        "mcpToolName": {
+          "type": "string"
+        },
+        "requiresApproval": {
+          "type": "boolean"
+        },
+        "inputSchema": {
+          "$ref": "#/$defs/JSONSchema"
+        },
+        "outputSchema": {
+          "$ref": "#/$defs/JSONSchema"
+        },
+        "version": {
+          "type": "string",
+          "minLength": 1
+        },
+        "execution": {
+          "$ref": "#/$defs/ToolExecutionContract"
+        },
+        "inputSemantics": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/CapabilityValueSemantic"
+          }
+        },
+        "outputSemantics": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/CapabilityValueSemantic"
+          }
         },
-        "mcpAdapterId": { "type": "string" },
-        "mcpToolName": { "type": "string" },
-        "requiresApproval": { "type": "boolean" },
-        "inputSchema": { "$ref": "#/$defs/JSONSchema" },
-        "outputSchema": { "$ref": "#/$defs/JSONSchema" }
+        "effects": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "producesAssessment": {
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false
+    },
+    "ToolExecutionContract": {
+      "type": "object",
+      "required": [
+        "mode",
+        "idempotent"
+      ],
+      "properties": {
+        "mode": {
+          "type": "string",
+          "enum": [
+            "sync",
+            "async"
+          ]
+        },
+        "idempotent": {
+          "type": "boolean"
+        },
+        "idempotencyKeyField": {
+          "type": "string",
+          "minLength": 1
+        },
+        "taskKind": {
+          "type": "string",
+          "minLength": 1
+        },
+        "statusTool": {
+          "type": "string",
+          "minLength": 1
+        },
+        "cancelTool": {
+          "type": "string",
+          "minLength": 1
+        },
+        "checks": {
+          "type": "array",
+          "maxItems": 20,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/CapabilityCheckReference"
+          }
+        },
+        "recoveryMode": {
+          "type": "string",
+          "enum": [
+            "original_call"
+          ]
+        }
       },
       "additionalProperties": false
     },
     "ResourceCapability": {
       "type": "object",
-      "required": ["name", "description", "permissionKeys"],
+      "required": [
+        "name",
+        "description",
+        "permissionKeys"
+      ],
       "properties": {
-        "name": { "type": "string" },
-        "description": { "type": "string" },
+        "name": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        },
         "permissionKeys": {
           "type": "array",
-          "items": { "type": "string" }
+          "items": {
+            "type": "string"
+          }
         },
         "requiredScopes": {
           "type": "array",
-          "items": { "type": "string" }
+          "items": {
+            "type": "string"
+          }
         },
-        "contextSchema": { "$ref": "#/$defs/JSONSchema" }
+        "contextSchema": {
+          "$ref": "#/$defs/JSONSchema"
+        }
       },
       "additionalProperties": false
     },
     "PromptCapability": {
       "type": "object",
-      "required": ["name", "description", "permissionKeys"],
+      "required": [
+        "name",
+        "description",
+        "permissionKeys"
+      ],
       "properties": {
-        "name": { "type": "string" },
-        "description": { "type": "string" },
+        "name": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        },
         "permissionKeys": {
           "type": "array",
-          "items": { "type": "string" }
+          "items": {
+            "type": "string"
+          }
         },
         "requiredScopes": {
           "type": "array",
-          "items": { "type": "string" }
+          "items": {
+            "type": "string"
+          }
         },
-        "argumentSchema": { "$ref": "#/$defs/JSONSchema" },
-        "contextSchema": { "$ref": "#/$defs/JSONSchema" }
+        "argumentSchema": {
+          "$ref": "#/$defs/JSONSchema"
+        },
+        "contextSchema": {
+          "$ref": "#/$defs/JSONSchema"
+        }
       },
       "additionalProperties": false
     },
     "SkillCapability": {
       "type": "object",
-      "required": ["id", "name", "category", "description"],
+      "required": [
+        "id",
+        "name",
+        "category",
+        "description"
+      ],
       "properties": {
-        "id": { "type": "string" },
-        "name": { "type": "string" },
-        "category": { "type": "string" },
-        "description": { "type": "string" },
+        "id": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string"
+        },
+        "category": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        },
         "capabilityRefs": {
           "type": "array",
-          "items": { "type": "string" }
+          "items": {
+            "type": "string"
+          }
         },
         "permissionKeys": {
           "type": "array",
-          "items": { "type": "string" }
+          "items": {
+            "type": "string"
+          }
         },
         "requiredScopes": {
           "type": "array",
-          "items": { "type": "string" }
+          "items": {
+            "type": "string"
+          }
         }
       },
       "additionalProperties": false
     },
     "ManifestSummary": {
       "type": "object",
-      "required": ["toolCount", "resourceCount", "promptCount", "skillCount", "deniedCount"],
+      "required": [
+        "toolCount",
+        "resourceCount",
+        "promptCount",
+        "skillCount",
+        "deniedCount"
+      ],
+      "properties": {
+        "toolCount": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "resourceCount": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "promptCount": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "skillCount": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "deniedCount": {
+          "type": "integer",
+          "minimum": 0
+        }
+      },
+      "additionalProperties": false
+    },
+    "CapabilityValueSemantic": {
+      "type": "object",
+      "required": [
+        "path",
+        "kind"
+      ],
       "properties": {
-        "toolCount": { "type": "integer", "minimum": 0 },
-        "resourceCount": { "type": "integer", "minimum": 0 },
-        "promptCount": { "type": "integer", "minimum": 0 },
-        "skillCount": { "type": "integer", "minimum": 0 },
-        "deniedCount": { "type": "integer", "minimum": 0 }
+        "path": {
+          "type": "string",
+          "pattern": "^/",
+          "maxLength": 512
+        },
+        "kind": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100
+        },
+        "unit": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 50
+        },
+        "scopePaths": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string",
+            "pattern": "^/",
+            "maxLength": 512
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "CapabilityCheckReference": {
+      "type": "object",
+      "required": [
+        "purpose",
+        "toolName",
+        "capabilityVersion"
+      ],
+      "properties": {
+        "purpose": {
+          "type": "string",
+          "enum": [
+            "availability",
+            "precondition",
+            "verification"
+          ]
+        },
+        "toolName": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200
+        },
+        "capabilityVersion": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100
+        }
       },
       "additionalProperties": false
     }
   }
 }
-

package/network/README.md

@@ -94,6 +94,33 @@ for authorization, routing, firewall configuration or accounting.
 - Validate ProtectedSet before NetworkLease coverage. A broad network lease
   cannot authorize a protected resource without a valid ResourceLease.
 
+## Managed VPN selection
+
+- Endpoint capability `managed-vpn-v1` enables the additive
+  `vpn.managed.prepare.*` and `vpn.managed.connect.*` messages. Legacy explicit
+  scope requests retain their existing contract; absent managed capability
+  never means implicit permission to use `external_vpn`.
+- Managed requests carry a short-lived intent ID/token bound to the enrolled
+  endpoint, authenticated user, published profile and selection-policy revisions.
+  The server resolves mode, site, space and resources; a caller cannot override
+  them. Prepare validates but does not consume the intent. A successful connection
+  consumes it atomically with the session and leases; replays cannot create a
+  second session. Tokens never enter audit logs or telemetry.
+- Manual selection stays on the requested gateway unless the published policy
+  explicitly permits manual-to-auto fallback. Auto only ranks gateways that
+  reach the same authorized target scope. Final admission rechecks topology,
+  live credentials, policy and capacity under the connection transaction.
+- Probe descriptors are authoritative control responses, bounded to 32 gateways,
+  10 samples, four concurrent requests and three seconds per request. Only fixed
+  HTTPS `/vpn/probe` targets are permitted; redirects and arbitrary caller URLs
+  are rejected. Gateway capability `vpn-probe-v1` enables `vpnProbe` verification
+  configuration. Probe tokens are endpoint- and gateway-bound and expire quickly.
+- HTTPS RTT is entrance-probe latency, not WireGuard or application RTT. A failed
+  HTTPS sample is a failed probe, not evidence of packet loss. Missing or expired
+  samples are unknown, never zero latency.
+- Gateway capability `vpn-metrics-v1` enables endpoint-peer `sessionId` and
+  `vpnProfileId` metadata. Site-link peers do not carry VPN user-session statistics.
+
 ## Ingest batches
 
 - Authenticate `producerId` from the transport credential; do not trust the
@@ -110,6 +137,19 @@ for authorization, routing, firewall configuration or accounting.
   limits before persistence.
 - Accounting and flow events are observability input only. They cannot create,
   renew, broaden or revoke a NetworkLease or ResourceLease.
+- `vpn.probe.batch` is endpoint-only and binds the intent, profile revision,
+  selection-policy revision, network epoch and measurement window. A successful
+  RTT sample count cannot exceed the number sent. Selection accepts only samples
+  from the intent's enrolled endpoint and approved candidate set.
+- `vpn.tunnel.stats` is gateway-only. Upload is the ingress gateway's endpoint-peer
+  received-byte delta; download is its transmitted-byte delta. Session, endpoint,
+  profile, ingress gateway and counter epoch identify the sample. Exclude transit
+  site-link peers and never sum endpoint copies into gateway-authoritative totals.
+- `vpn.gateway.health` is gateway-only, carries observed runtime readiness and
+  endpoint-peer count, and is not an administrator-supplied health override.
+- VPN aggregate queries enforce trusted session/gateway bindings and authorized
+  scope before aggregation. Counters reset with a new epoch; absent data stays
+  absent. Quantiles must come from samples, not averages of per-gateway quantiles.
 
 Consumers must cover these rules with deterministic tests. Failure is
 fail-closed for control messages and bounded reject/drop-with-counter behavior