@opensoha/contracts 0.1.15 → 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 = "58321138575c22b20933cf2c1db2742b741a123bb8f6a2983bb436e84be4e58a"
-	PermissionCatalogSHA256 = "38ac1a2e7087ff4831e8f6390b804e32f918b49b9af3165fdf2df286d64fe3c8"
+	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 {