@opensoha/contracts 0.1.5 → 0.1.7

package/auth/permission-catalog.schema.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.opensoha.dev/auth/permission-catalog.schema.json",
+  "title": "OpenSoha Permission Catalog",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "catalogVersion", "contentHash", "permissions"],
+  "properties": {
+    "schemaVersion": { "const": "authorization.opensoha.io/v1" },
+    "catalogVersion": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" },
+    "contentHash": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "permissions": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/permission" }
+    }
+  },
+  "$defs": {
+    "permission": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "key",
+        "domain",
+        "resource",
+        "action",
+        "displayName",
+        "riskLevel",
+        "scopeKinds",
+        "approvalPolicy",
+        "status",
+        "assignable"
+      ],
+      "properties": {
+        "key": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9_-]*(?:\\.[a-z][a-z0-9_-]*)+$"
+        },
+        "domain": { "type": "string", "pattern": "^[a-z][a-z0-9_-]*$" },
+        "resource": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]*$" },
+        "action": { "type": "string", "pattern": "^[a-z][a-z0-9_-]*$" },
+        "displayName": { "type": "string", "minLength": 1 },
+        "riskLevel": { "type": "string", "enum": ["read", "mutate", "execute", "high"] },
+        "scopeKinds": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "enum": ["tenant", "workspace", "cluster", "namespace", "project", "resource", "owner"]
+          }
+        },
+        "approvalPolicy": { "type": "string", "enum": ["never", "eligible", "required"] },
+        "status": { "type": "string", "enum": ["active", "legacy"] },
+        "assignable": { "type": "boolean" },
+        "legacyAliases": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "legacyCapabilities": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "type": "string", "pattern": "^[a-z][a-z0-9_-]*$" }
+        },
+        "replacedBy": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    }
+  }
+}

package/capabilities/cluster-capability-matrix.schema.json

@@ -48,6 +48,11 @@
       "properties": {
         "status": { "$ref": "#/$defs/CapabilityStatus" },
         "reason": { "type": "string", "minLength": 1 },
+        "notes": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true
+        },
         "diagnostic": { "type": "string" },
         "requiredAgentVersion": { "type": "string" },
         "requiredScopes": {
@@ -71,10 +76,34 @@
         "label": { "type": "string", "minLength": 1 },
         "category": {
           "type": "string",
-          "enum": ["kubernetes", "helm", "yaml", "logs", "exec", "port-forward", "docker", "runtime"]
+          "enum": [
+            "kubernetes",
+            "helm",
+            "yaml",
+            "logs",
+            "exec",
+            "port-forward",
+            "docker",
+            "runtime",
+            "platform",
+            "workloads",
+            "configuration",
+            "access",
+            "network",
+            "storage",
+            "extensions",
+            "delivery",
+            "observability"
+          ]
+        },
+        "requiredScopes": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true
         },
         "riskLevel": { "$ref": "#/$defs/RiskLevel" },
         "requiresApproval": { "type": "boolean" },
+        "docsUrl": { "type": "string", "minLength": 1 },
         "direct": { "$ref": "#/$defs/ModeSupport" },
         "agent": { "$ref": "#/$defs/ModeSupport" },
         "metadata": {

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

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.5",
+  "version": "0.1.7",
   "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.5",
+  "version": "0.1.7",
   "generatedFrom": "openapi/soha-api.yaml",
   "entries": [
     {

package/examples/gateway-manifest/minimal.json

@@ -10,22 +10,22 @@
     "teams": [],
     "projects": [],
     "tags": [],
-    "permissionKeys": ["ai.gateway.tools.read", "k8s.pods.read"]
+    "permissionKeys": ["ai.gateway.view", "platform.pods.view"]
   },
   "caller": {
     "identityMode": "user",
     "source": "cli"
   },
-  "permissionKeys": ["ai.gateway.tools.read", "k8s.pods.read"],
+  "permissionKeys": ["ai.gateway.view", "platform.pods.view"],
   "tools": [
     {
-      "name": "k8s.list_pods",
+      "name": "k8s.pods.list",
       "title": "List pods",
       "description": "List Kubernetes pods in a namespace.",
       "domain": "kubernetes",
       "action": "read",
       "riskLevel": "read",
-      "permissionKeys": ["k8s.pods.read"],
+      "permissionKeys": ["platform.pods.view"],
       "requiredScopes": ["cluster", "namespace"],
       "mcpAdapterId": "builtin.kubernetes",
       "mcpToolName": "k8s.pods.list",
@@ -57,8 +57,8 @@
       "name": "Kubernetes SRE",
       "category": "ai-gateway",
       "description": "Read-only cluster diagnosis skill.",
-      "capabilityRefs": ["k8s.list_pods"],
-      "permissionKeys": ["k8s.pods.read"],
+      "capabilityRefs": ["k8s.pods.list"],
+      "permissionKeys": ["platform.pods.view"],
       "requiredScopes": ["cluster", "namespace"]
     }
   ],

package/examples/openapi/agent-run-tool-call-request.json

@@ -4,7 +4,7 @@
   "agentId": "agent-01",
   "toolBindingId": "binding-01",
   "adapterId": "builtin.kubernetes",
-  "toolName": "k8s.list_pods",
+  "toolName": "k8s.pods.list",
   "input": {
     "namespace": "default"
   }

package/examples/openapi/agent-tool-call-result-envelope.json

@@ -2,7 +2,7 @@
   "data": {
     "runId": "run-01",
     "toolExecution": {
-      "toolName": "k8s.list_pods",
+      "toolName": "k8s.pods.list",
       "status": "succeeded",
       "requestId": "req-01"
     },

package/examples/openapi/gateway-manifest-envelope.json

@@ -11,22 +11,22 @@
       "teams": [],
       "projects": [],
       "tags": [],
-      "permissionKeys": ["ai.gateway.tools.read", "k8s.pods.read"]
+      "permissionKeys": ["ai.gateway.view", "platform.pods.view"]
     },
     "caller": {
       "identityMode": "user",
       "source": "web"
     },
-    "permissionKeys": ["ai.gateway.tools.read", "k8s.pods.read"],
+    "permissionKeys": ["ai.gateway.view", "platform.pods.view"],
     "tools": [
       {
-        "name": "k8s.list_pods",
+        "name": "k8s.pods.list",
         "title": "List pods",
         "description": "List Kubernetes pods in a namespace.",
         "domain": "kubernetes",
         "action": "read",
         "riskLevel": "read",
-        "permissionKeys": ["k8s.pods.read"],
+        "permissionKeys": ["platform.pods.view"],
         "requiredScopes": ["cluster", "namespace"],
         "requiresApproval": false,
         "inputSchema": {

package/examples/openapi/tool-invocation-request.json

@@ -1,5 +1,5 @@
 {
-  "toolName": "k8s.list_pods",
+  "toolName": "k8s.pods.list",
   "input": {
     "clusterId": "default",
     "namespace": "default"

package/examples/openapi/tool-invocation-result-envelope.json

@@ -1,6 +1,6 @@
 {
   "data": {
-    "toolName": "k8s.list_pods",
+    "toolName": "k8s.pods.list",
     "riskLevel": "read",
     "requiresApproval": false,
     "result": "succeeded",

package/examples/plugin-manifest/skill-pack.json

@@ -14,11 +14,11 @@
     "skills": ["skills/ai-gateway/k8s-sre/SKILL.md"]
   },
   "capabilities": {
-    "tools": ["k8s.list_pods"],
+    "tools": ["k8s.pods.list"],
     "skills": ["k8s-sre"]
   },
   "permissions": {
-    "required": ["k8s.pods.read"],
+    "required": ["platform.pods.view"],
     "domain": ["kubernetes"]
   },
   "runtime": {

package/examples/skill-manifest/k8s-sre.json

@@ -4,8 +4,8 @@
   "version": "0.1.0",
   "category": "ai-gateway",
   "description": "Read-only Kubernetes troubleshooting skill.",
-  "capabilityRefs": ["k8s.list_pods"],
-  "permissionKeys": ["k8s.pods.read"],
+  "capabilityRefs": ["k8s.pods.list"],
+  "permissionKeys": ["platform.pods.view"],
   "requiredScopes": ["cluster", "namespace"],
   "providerSkillRefs": [
     {

package/examples/token-claims/service-account.json

@@ -10,6 +10,6 @@
   "subjectId": "sa-1",
   "tenantId": "default",
   "workspaceId": "default",
-  "permissionKeys": ["ai.gateway.tools.read", "k8s.pods.read"],
+  "permissionKeys": ["ai.gateway.view", "platform.pods.view"],
   "scopes": ["ai:read", "k8s:read"]
 }

package/fixtures/json-schema/cluster-capability-matrix/valid/runtime-parity.json

@@ -6,14 +6,17 @@
       "key": "kubernetes.yaml.apply",
       "label": "Apply Kubernetes YAML",
       "category": "yaml",
+      "requiredScopes": ["cluster", "namespace"],
       "riskLevel": "mutate",
       "requiresApproval": true,
+      "docsUrl": "/operations/kubernetes-yaml",
       "direct": {
         "status": "available",
         "requiredScopes": ["cluster:write", "kubernetes:apply"]
       },
       "agent": {
         "status": "available",
+        "notes": ["Requires the resource mutation allowlist."],
         "requiredAgentVersion": "0.1.0",
         "requiredScopes": ["agent:kubernetes:apply"]
       },

package/fixtures/json-schema/gateway-manifest/valid/minimal.json

@@ -10,22 +10,22 @@
     "teams": [],
     "projects": [],
     "tags": [],
-    "permissionKeys": ["ai.gateway.tools.read"]
+    "permissionKeys": ["ai.gateway.view"]
   },
   "caller": {
     "identityMode": "user",
     "source": "cli"
   },
-  "permissionKeys": ["ai.gateway.tools.read"],
+  "permissionKeys": ["ai.gateway.view"],
   "tools": [
     {
-      "name": "k8s.list_pods",
+      "name": "k8s.pods.list",
       "title": "List pods",
       "description": "List Kubernetes pods in a namespace.",
       "domain": "kubernetes",
       "action": "read",
       "riskLevel": "read",
-      "permissionKeys": ["k8s.pods.read"],
+      "permissionKeys": ["platform.pods.view"],
       "requiresApproval": false,
       "inputSchema": {
         "type": "object",

package/fixtures/json-schema/permission-catalog/invalid/missing-action.json

@@ -0,0 +1,18 @@
+{
+  "schemaVersion": "authorization.opensoha.io/v1",
+  "catalogVersion": "1.0.0",
+  "contentHash": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
+  "permissions": [
+    {
+      "key": "virtualization.vms.view",
+      "domain": "virtualization",
+      "resource": "vms",
+      "displayName": "View virtual machines",
+      "riskLevel": "read",
+      "scopeKinds": ["workspace", "resource"],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    }
+  ]
+}

package/fixtures/json-schema/permission-catalog/valid/minimal.json

@@ -0,0 +1,19 @@
+{
+  "schemaVersion": "authorization.opensoha.io/v1",
+  "catalogVersion": "1.0.0",
+  "contentHash": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
+  "permissions": [
+    {
+      "key": "virtualization.vms.view",
+      "domain": "virtualization",
+      "resource": "vms",
+      "action": "view",
+      "displayName": "View virtual machines",
+      "riskLevel": "read",
+      "scopeKinds": ["workspace", "resource"],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    }
+  ]
+}

package/fixtures/json-schema/skill-manifest/valid/minimal.json

@@ -3,6 +3,6 @@
   "name": "Kubernetes SRE",
   "version": "0.1.0",
   "category": "ai-gateway",
-  "capabilityRefs": ["k8s.list_pods"],
-  "permissionKeys": ["k8s.pods.read"]
+  "capabilityRefs": ["k8s.pods.list"],
+  "permissionKeys": ["platform.pods.view"]
 }

package/fixtures/json-schema/token-claims/valid/service-account.json

@@ -10,6 +10,6 @@
   "subjectId": "sa-1",
   "tenantId": "default",
   "workspaceId": "default",
-  "permissionKeys": ["ai.gateway.tools.read"],
+  "permissionKeys": ["ai.gateway.view"],
   "scopes": ["ai:read"]
 }

package/fixtures/openapi/AIGatewayManifestEnvelope/valid/minimal.json

@@ -15,7 +15,7 @@
     "caller": {
       "identityMode": "user"
     },
-    "permissionKeys": ["ai.gateway.tools.read"],
+    "permissionKeys": ["ai.gateway.view"],
     "tools": [],
     "resources": [],
     "prompts": [],

package/fixtures/openapi/AccessRoleInput/invalid/missing-permissions.json

@@ -0,0 +1,4 @@
+{
+  "name": "vm-builder",
+  "scope": "custom"
+}

package/fixtures/openapi/AccessRoleInput/valid/granular-vm-operator.json

@@ -0,0 +1,10 @@
+{
+  "name": "vm-builder",
+  "scope": "custom",
+  "capabilities": [],
+  "permissionKeys": [
+    "virtualization.vms.view",
+    "virtualization.vms.create",
+    "virtualization.vms.resize"
+  ]
+}

package/fixtures/openapi/AgentInstallationEnvelope/invalid/missing-command.json

@@ -0,0 +1,7 @@
+{
+  "data": {
+    "clusterId": "cluster-1",
+    "manifestUrl": "https://soha.example.com/api/v1/kubernetes/agent-installations/dGlja2V0.manifest/manifest.yaml",
+    "expiresAt": "2026-08-08T10:15:00Z"
+  }
+}

package/fixtures/openapi/AgentInstallationEnvelope/valid/minimal.json

@@ -0,0 +1,8 @@
+{
+  "data": {
+    "clusterId": "cluster-1",
+    "manifestUrl": "https://soha.example.com/api/v1/kubernetes/agent-installations/dGlja2V0.manifest/manifest.yaml",
+    "command": "kubectl apply -f https://soha.example.com/api/v1/kubernetes/agent-installations/dGlja2V0.manifest/manifest.yaml",
+    "expiresAt": "2026-08-08T10:15:00Z"
+  }
+}

package/fixtures/openapi/ApplicationInput/invalid/missing-key.json

@@ -0,0 +1,4 @@
+{
+  "name": "Payments",
+  "enabled": true
+}

package/fixtures/openapi/ApplicationInput/valid/minimal.json

@@ -0,0 +1,5 @@
+{
+  "name": "Payments",
+  "key": "payments",
+  "enabled": true
+}

package/fixtures/openapi/AuthorizationDecision/invalid/missing-reason.json

@@ -0,0 +1,7 @@
+{
+  "status": "deny",
+  "permissionKey": "virtualization.vms.delete",
+  "action": "delete",
+  "resource": { "type": "virtualization.vm", "id": "vm-01" },
+  "policyVersion": "authorization.opensoha.io/v1"
+}

package/fixtures/openapi/AuthorizationDecision/valid/deny-vm-delete.json

@@ -0,0 +1,16 @@
+{
+  "status": "deny",
+  "permissionKey": "virtualization.vms.delete",
+  "action": "delete",
+  "resource": {
+    "type": "virtualization.vm",
+    "id": "vm-01",
+    "workspaceId": "default"
+  },
+  "effectiveScope": {
+    "workspaceIds": ["default"]
+  },
+  "reasonCode": "missing_permission",
+  "policyVersion": "authorization.opensoha.io/v1",
+  "allowedActions": ["view", "create", "resize"]
+}

package/fixtures/openapi/HelmReleaseImportRequest/invalid/empty-releases.json

@@ -0,0 +1,10 @@
+{
+  "clusterId": "cluster-prod",
+  "namespace": "payments",
+  "applicationKey": "payments",
+  "applicationName": "Payments",
+  "environmentKey": "prod",
+  "environmentName": "Production",
+  "ownershipMode": "managed",
+  "releases": []
+}

package/fixtures/openapi/HelmReleaseImportRequest/valid/managed.json

@@ -0,0 +1,14 @@
+{
+  "clusterId": "cluster-prod",
+  "namespace": "payments",
+  "applicationKey": "payments",
+  "applicationName": "Payments",
+  "environmentKey": "prod",
+  "environmentName": "Production",
+  "ownershipMode": "managed",
+  "releases": [
+    {
+      "releaseName": "payments"
+    }
+  ]
+}

package/fixtures/openapi/HelmReleaseImportResultEnvelope/invalid/missing-mode.json

@@ -0,0 +1,20 @@
+{
+  "data": {
+    "application": {
+      "id": "app-1",
+      "key": "payments",
+      "name": "Payments",
+      "created": true
+    },
+    "environment": {
+      "id": "env-1",
+      "key": "prod",
+      "name": "Production",
+      "created": false
+    },
+    "applicationEnvironmentId": "app-env-1",
+    "applicationEnvironmentCreated": true,
+    "services": [],
+    "targets": []
+  }
+}

package/fixtures/openapi/HelmReleaseImportResultEnvelope/valid/created.json

@@ -0,0 +1,35 @@
+{
+  "data": {
+    "application": {
+      "id": "app-1",
+      "key": "payments",
+      "name": "Payments",
+      "created": true
+    },
+    "environment": {
+      "id": "env-1",
+      "key": "prod",
+      "name": "Production",
+      "created": false
+    },
+    "applicationEnvironmentId": "app-env-1",
+    "applicationEnvironmentCreated": true,
+    "ownershipMode": "managed",
+    "services": [
+      {
+        "id": "service-1",
+        "key": "helm-payments",
+        "name": "payments",
+        "releaseName": "payments",
+        "created": true
+      }
+    ],
+    "targets": [
+      {
+        "id": "target-1",
+        "releaseName": "payments",
+        "created": true
+      }
+    ]
+  }
+}

package/fixtures/openapi/KubernetesImportCandidateListEnvelope/invalid/unknown-kind.json

@@ -0,0 +1,14 @@
+{
+  "items": [
+    {
+      "clusterId": "cluster-prod",
+      "namespace": "payments",
+      "workloadKind": "Pod",
+      "workloadName": "payments-api-123",
+      "desiredReplicas": 1,
+      "readyReplicas": 1,
+      "relatedResources": []
+    }
+  ],
+  "truncated": false
+}

package/fixtures/openapi/KubernetesImportCandidateListEnvelope/valid/grouped.json

@@ -0,0 +1,31 @@
+{
+  "items": [
+    {
+      "clusterId": "cluster-prod",
+      "namespace": "payments",
+      "workloadKind": "Deployment",
+      "workloadName": "payments-api",
+      "desiredReplicas": 3,
+      "readyReplicas": 3,
+      "containers": ["api"],
+      "labels": {
+        "app": "payments-api"
+      },
+      "relatedResources": [
+        {
+          "kind": "Service",
+          "name": "payments-api"
+        },
+        {
+          "kind": "Ingress",
+          "name": "payments"
+        },
+        {
+          "kind": "HorizontalPodAutoscaler",
+          "name": "payments-api"
+        }
+      ]
+    }
+  ],
+  "truncated": false
+}

package/fixtures/openapi/KubernetesServiceImportRequest/invalid/unsupported-mode.json

@@ -0,0 +1,15 @@
+{
+  "clusterId": "cluster-prod",
+  "namespace": "payments",
+  "applicationKey": "payments",
+  "applicationName": "Payments",
+  "environmentKey": "prod",
+  "environmentName": "Production",
+  "ownershipMode": "takeover",
+  "workloads": [
+    {
+      "workloadKind": "Deployment",
+      "workloadName": "payments-api"
+    }
+  ]
+}

package/fixtures/openapi/KubernetesServiceImportRequest/valid/managed.json

@@ -0,0 +1,15 @@
+{
+  "clusterId": "cluster-prod",
+  "namespace": "payments",
+  "applicationKey": "payments",
+  "applicationName": "Payments",
+  "environmentKey": "prod",
+  "environmentName": "Production",
+  "ownershipMode": "managed",
+  "workloads": [
+    {
+      "workloadKind": "Deployment",
+      "workloadName": "payments-api"
+    }
+  ]
+}