@opensoha/contracts 0.1.16 → 0.1.17

package/COMPATIBILITY.md

@@ -281,6 +281,52 @@ rename `operationId`, `operationKind`, `runnerId`, `state`, `occurredAt`,
 `evidence`, `finalState`, or `callback`; must not add new required fields; and
 must not narrow existing lifecycle state names or final status values.
 
+## Network Runtime Protocol
+
+`network/network-runtime-protocol.schema.json` owns messages exchanged by
+network-control, endpoint services and network gateways. The contract carries
+runtime identity, configuration and policy versions, bounded lease grants and
+apply/revoke acknowledgements. It must never carry WireGuard private keys,
+RADIUS shared secrets, passwords, EAP private material or mihomo subscription
+credentials.
+
+For `0.1.x`, patch releases may add optional fields and new message types with
+strict payload definitions. They must not remove or rename `schemaVersion`,
+`messageId`, `messageType`, `producerId`, `runtimeId`, `runtimeKind`,
+`occurredAt`, `expiresAt` or `payload`; must not remove existing message,
+runtime-kind, access-profile or status enum values; and must not loosen unknown
+field rejection. Existing lease identity, subject/device binding, policy
+version and expiry fields must remain required.
+
+NAS authorization and session control use the same versioned envelope. Their
+payloads contain only Soha identity references, bounded standard RADIUS
+attributes and command acknowledgements. Public management bindings map a NAS
+to one registered runtime/site and an access profile to site enforcement
+attributes; neither contract may add RADIUS shared secrets or authentication
+credential material.
+
+WireGuard enrollment carries only a public key. VPN connection authorization
+creates a session-scoped NetworkLease; desired configuration may add a strict
+WireGuard block with overlay addresses, peers, split routes and default-deny
+firewall rules. Private keys never cross this contract. Existing consumers
+must ignore no fields because runtime messages remain closed; therefore a
+consumer advertises `wireguard` only after it supports the full block and its
+configuration version/readback semantics.
+
+## Network Ingest Event
+
+`network/network-ingest-event.schema.json` owns bounded, replayable telemetry
+batches sent to `/api/ingest/v1/**`. Heartbeat, RADIUS Accounting, flow
+aggregate and connection summary payloads remain typed and cannot be treated
+as authorization state.
+
+For `0.1.x`, patch releases may add optional fields, producer kinds and event
+types with strict payload definitions. They must not remove or rename
+`schemaVersion`, `batchId`, `producerId`, `producerKind`, `sentAt`, `events`,
+event `id`, `type`, `sequence`, `occurredAt` or `payload`; must not remove
+existing enum values; must not raise the 1,000-event batch maximum without a
+resource-limit review; and must not introduce an open provider payload object.
+
 ## Permission Catalog
 
 `auth/permission-catalog.json` owns grantable OpenSoha resource/action keys,

package/README.md

@@ -32,6 +32,8 @@ auth/token-claims.schema.json         Token/JWT claims contract
 auth/permission-catalog.json          Canonical resource/action permission catalog
 auth/permission-catalog.schema.json   Permission definition and migration metadata
 connectors/connector-event-envelope.schema.json  Connector runtime event batch envelope
+network/network-runtime-protocol.schema.json  Network control/runtime message contract
+network/network-ingest-event.schema.json  Bounded heartbeat, Accounting and flow event batches
 gen/go/sohaapi                        Go SDK types for stable cross-repo contracts
 gen/ts/sohaapi                        TypeScript SDK types for stable Web contracts
 ```
@@ -147,6 +149,12 @@ failure.
 
 ## Consumer Matrix
 
+Network runtime schemas and network-access DTOs require `0.1.17` or later;
+they are absent from npm `0.1.16` and Go `v0.1.15`. For unpublished changes,
+use the local consumer matrix below: it packs this checkout for Web and
+supplies an isolated Go workspace. After publishing, update consumer versions
+and lockfiles and verify them without the local override.
+
 The cross-repository consumer gate is:
 
 ```sh
@@ -163,9 +171,10 @@ npm run check:consumers -- --consumer soha-cli --require-all
 npm run check:consumers -- --consumer soha-agent --require-all
 ```
 
-Go consumers run in a temporary `go.work` that includes this checkout, so
-changes are tested against the local contracts module. `soha-web` runs
-`npm ci` and `npm run build` against its `file:../soha-contracts` dependency.
+Go consumers run in a temporary `go.work` that replaces the contracts module
+with this checkout. `soha-web` runs `npm ci`, installs a packed copy of this
+checkout without changing its dependency manifest or lockfile, and builds
+against that package.
 
 Use `--dry-run` to inspect the discovered commands without executing consumer
 builds.

package/auth/catalog_generated.go

@@ -6,8 +6,8 @@ import _ "embed"
 
 const (
 	PermissionCatalogVersion = "2.0.0"
-	PermissionCatalogContentSHA256 = "5aa6fa361c2ab8d987415fb1eb93218510deb9359a68212dfe86655dbfaeea5e"
-	PermissionCatalogSHA256 = "01c80a71427e3d7f4898212fb1667405c27f1b798318d9eac86ece8262cd188c"
+	PermissionCatalogContentSHA256 = "f744896d362070a1e7cdc1eda89c046bee8132f37c6f323dafdd05644e2dbd3c"
+	PermissionCatalogSHA256 = "354ad414691ff0578d805036bbbe80da28d242d0bbabe4699e490af1b6bd87bb"
 )
 
 //go:embed permission-catalog.json

package/auth/catalog_test.go

@@ -52,6 +52,38 @@ func TestPermissionCatalogIncludesVirtualizationStorageView(t *testing.T) {
 	t.Fatal("virtualization.storage.view is missing")
 }
 
+func TestPermissionCatalogIncludesDeliveryEnvironmentApproval(t *testing.T) {
+	var catalog struct {
+		Permissions []struct {
+			Key            string   `json:"key"`
+			Domain         string   `json:"domain"`
+			Resource       string   `json:"resource"`
+			Action         string   `json:"action"`
+			RiskLevel      string   `json:"riskLevel"`
+			ScopeKinds     []string `json:"scopeKinds"`
+			ApprovalPolicy string   `json:"approvalPolicy"`
+			Status         string   `json:"status"`
+			Assignable     bool     `json:"assignable"`
+		} `json:"permissions"`
+	}
+	if err := json.Unmarshal(PermissionCatalogJSON(), &catalog); err != nil {
+		t.Fatalf("decode permission catalog: %v", err)
+	}
+	for _, permission := range catalog.Permissions {
+		if permission.Key != "delivery.application-environments.approve" {
+			continue
+		}
+		if permission.Domain != "delivery" || permission.Resource != "application-environments" || permission.Action != "approve" ||
+			permission.RiskLevel != "high" || permission.ApprovalPolicy != "eligible" || permission.Status != "active" ||
+			!permission.Assignable || len(permission.ScopeKinds) != 3 || permission.ScopeKinds[0] != "workspace" ||
+			permission.ScopeKinds[1] != "project" || permission.ScopeKinds[2] != "resource" {
+			t.Fatalf("unexpected delivery environment approval permission: %#v", permission)
+		}
+		return
+	}
+	t.Fatal("delivery.application-environments.approve is missing")
+}
+
 func TestPermissionCatalogIncludesIndependentResourceCreationEntry(t *testing.T) {
 	var catalog struct {
 		Permissions []struct {

package/auth/permission-catalog.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "authorization.opensoha.io/v1",
   "catalogVersion": "2.0.0",
-  "contentHash": "sha256:5aa6fa361c2ab8d987415fb1eb93218510deb9359a68212dfe86655dbfaeea5e",
+  "contentHash": "sha256:f744896d362070a1e7cdc1eda89c046bee8132f37c6f323dafdd05644e2dbd3c",
   "permissions": [
     {
       "key": "access.directory.create",
@@ -2468,6 +2468,22 @@
       "status": "active",
       "assignable": true
     },
+    {
+      "key": "delivery.application-environments.approve",
+      "domain": "delivery",
+      "resource": "application-environments",
+      "action": "approve",
+      "displayName": "审批应用环境发布",
+      "riskLevel": "high",
+      "scopeKinds": [
+        "workspace",
+        "project",
+        "resource"
+      ],
+      "approvalPolicy": "eligible",
+      "status": "active",
+      "assignable": true
+    },
     {
       "key": "delivery.application-environments.create",
       "domain": "delivery",
@@ -4502,6 +4518,518 @@
       "status": "active",
       "assignable": true
     },
+    {
+      "key": "network_access.access_grants.create",
+      "domain": "network_access",
+      "resource": "access_grants",
+      "action": "create",
+      "displayName": "申请受保护网络资源访问",
+      "riskLevel": "high",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "eligible",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.access_grants.revoke",
+      "domain": "network_access",
+      "resource": "access_grants",
+      "action": "revoke",
+      "displayName": "撤销受保护网络资源访问凭证",
+      "riskLevel": "high",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "eligible",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.access_grants.view",
+      "domain": "network_access",
+      "resource": "access_grants",
+      "action": "view",
+      "displayName": "查看受保护网络资源访问凭证",
+      "riskLevel": "read",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.endpoint_devices.update",
+      "domain": "network_access",
+      "resource": "endpoint_devices",
+      "action": "update",
+      "displayName": "修改网络接入设备",
+      "riskLevel": "mutate",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.endpoint_devices.view",
+      "domain": "network_access",
+      "resource": "endpoint_devices",
+      "action": "view",
+      "displayName": "查看网络接入设备",
+      "riskLevel": "read",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.enrollments.create",
+      "domain": "network_access",
+      "resource": "enrollments",
+      "action": "create",
+      "displayName": "创建网络运行时注册令牌",
+      "riskLevel": "high",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "eligible",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.enrollments.revoke",
+      "domain": "network_access",
+      "resource": "enrollments",
+      "action": "revoke",
+      "displayName": "撤销网络运行时注册",
+      "riskLevel": "high",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "eligible",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.enrollments.view",
+      "domain": "network_access",
+      "resource": "enrollments",
+      "action": "view",
+      "displayName": "查看网络运行时注册",
+      "riskLevel": "read",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.gateways.create",
+      "domain": "network_access",
+      "resource": "gateways",
+      "action": "create",
+      "displayName": "创建网络接入网关",
+      "riskLevel": "high",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "eligible",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.gateways.update",
+      "domain": "network_access",
+      "resource": "gateways",
+      "action": "update",
+      "displayName": "更新网络接入网关",
+      "riskLevel": "high",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "eligible",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.gateways.view",
+      "domain": "network_access",
+      "resource": "gateways",
+      "action": "view",
+      "displayName": "查看网络接入网关",
+      "riskLevel": "read",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.mihomo_profiles.create",
+      "domain": "network_access",
+      "resource": "mihomo_profiles",
+      "action": "create",
+      "displayName": "创建 mihomo 代理配置",
+      "riskLevel": "high",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "eligible",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.mihomo_profiles.delete",
+      "domain": "network_access",
+      "resource": "mihomo_profiles",
+      "action": "delete",
+      "displayName": "删除 mihomo 代理配置",
+      "riskLevel": "high",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "eligible",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.mihomo_profiles.update",
+      "domain": "network_access",
+      "resource": "mihomo_profiles",
+      "action": "update",
+      "displayName": "更新 mihomo 代理配置",
+      "riskLevel": "high",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "eligible",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.mihomo_profiles.view",
+      "domain": "network_access",
+      "resource": "mihomo_profiles",
+      "action": "view",
+      "displayName": "查看 mihomo 代理配置",
+      "riskLevel": "read",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.policy.create",
+      "domain": "network_access",
+      "resource": "policy",
+      "action": "create",
+      "displayName": "创建网络访问策略",
+      "riskLevel": "mutate",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.policy.delete",
+      "domain": "network_access",
+      "resource": "policy",
+      "action": "delete",
+      "displayName": "删除网络访问策略",
+      "riskLevel": "high",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "eligible",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.policy.update",
+      "domain": "network_access",
+      "resource": "policy",
+      "action": "update",
+      "displayName": "修改和发布网络访问策略",
+      "riskLevel": "mutate",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.policy.view",
+      "domain": "network_access",
+      "resource": "policy",
+      "action": "view",
+      "displayName": "查看和预演网络访问策略",
+      "riskLevel": "read",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.resources.create",
+      "domain": "network_access",
+      "resource": "resources",
+      "action": "create",
+      "displayName": "创建网络资源",
+      "riskLevel": "mutate",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.resources.delete",
+      "domain": "network_access",
+      "resource": "resources",
+      "action": "delete",
+      "displayName": "删除网络资源",
+      "riskLevel": "mutate",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.resources.update",
+      "domain": "network_access",
+      "resource": "resources",
+      "action": "update",
+      "displayName": "修改网络资源",
+      "riskLevel": "mutate",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.resources.view",
+      "domain": "network_access",
+      "resource": "resources",
+      "action": "view",
+      "displayName": "查看网络资源",
+      "riskLevel": "read",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.sites.create",
+      "domain": "network_access",
+      "resource": "sites",
+      "action": "create",
+      "displayName": "创建网络站点",
+      "riskLevel": "mutate",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.sites.delete",
+      "domain": "network_access",
+      "resource": "sites",
+      "action": "delete",
+      "displayName": "删除网络站点",
+      "riskLevel": "mutate",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.sites.update",
+      "domain": "network_access",
+      "resource": "sites",
+      "action": "update",
+      "displayName": "修改网络站点",
+      "riskLevel": "mutate",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.sites.view",
+      "domain": "network_access",
+      "resource": "sites",
+      "action": "view",
+      "displayName": "查看网络站点",
+      "riskLevel": "read",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.spaces.create",
+      "domain": "network_access",
+      "resource": "spaces",
+      "action": "create",
+      "displayName": "创建网络空间",
+      "riskLevel": "mutate",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.spaces.delete",
+      "domain": "network_access",
+      "resource": "spaces",
+      "action": "delete",
+      "displayName": "删除网络空间",
+      "riskLevel": "mutate",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.spaces.update",
+      "domain": "network_access",
+      "resource": "spaces",
+      "action": "update",
+      "displayName": "修改网络空间",
+      "riskLevel": "mutate",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.spaces.view",
+      "domain": "network_access",
+      "resource": "spaces",
+      "action": "view",
+      "displayName": "查看网络空间",
+      "riskLevel": "read",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.telemetry.view",
+      "domain": "network_access",
+      "resource": "telemetry",
+      "action": "view",
+      "displayName": "查看网络遥测汇总",
+      "riskLevel": "read",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
     {
       "key": "observe.ai.chat",
       "domain": "observe",