@opensoha/contracts 0.1.5 → 0.1.7

package/COMPATIBILITY.md

@@ -281,6 +281,19 @@ 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.
 
+## Permission Catalog
+
+`auth/permission-catalog.json` owns grantable OpenSoha resource/action keys,
+risk and scope metadata, approval posture, and temporary legacy aliases. Its
+`contentHash` covers the ordered permission definitions; the Go `auth` package
+also publishes the full artifact hash.
+
+For `0.1.x`, patch releases may add active permission definitions and legacy
+aliases. They must not remove active definitions, change an active key's
+resource/action meaning, or make a legacy alias authorize a broader action.
+Coarse keys become non-assignable before removal, and are removed only after
+role migration and consumer conformance prove no active dependency.
+
 ## Consumer Adoption
 
 Recommended adoption flow:

package/README.md

@@ -29,6 +29,8 @@ skills/skill-manifest.schema.json     Official skill front matter contract
 plugins/plugin-manifest.schema.json   Plugin and marketplace package manifest
 events/event-envelope.schema.json     Shared event envelope contract
 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
 gen/go/sohaapi                        Go SDK types for stable cross-repo contracts
 gen/ts/sohaapi                        TypeScript SDK types for stable Web contracts
@@ -78,6 +80,10 @@ npm run check:generated
 temporary directory and compares it to committed files. It must not rewrite
 generated files during a freshness check. The Go `openapi` package exposes
 copies of both formats plus `Version`, `YAMLSHA256`, and `JSONSHA256`.
+The Go `auth` package embeds the canonical permission catalog and exposes its
+catalog version, definition hash, and artifact hash. Refresh it with
+`npm run generate:permissions`; consumers conformance-check their local keys
+against this artifact instead of maintaining a second catalog.
 
 The Go client in `gen/go/sohaapi/client.go` intentionally keeps a stable
 hand-written method surface while DTOs are generated from OpenAPI. For

package/auth/catalog_generated.go

@@ -0,0 +1,17 @@
+// Code generated from OpenSoha permission contracts. DO NOT EDIT.
+
+package auth
+
+import _ "embed"
+
+const (
+	PermissionCatalogVersion = "1.3.0"
+	PermissionCatalogContentSHA256 = "182dbfb4b9962dc4a0c344c2ce7622ec4424cf5ff0892a73b0b6806eddf6f2c7"
+	PermissionCatalogSHA256 = "f9956b1ee4e3d981a4e93e7078006aa915a5eb18fb2347fa0d81bc8346b8958b"
+)
+
+//go:embed permission-catalog.json
+var permissionCatalogJSON []byte
+
+// PermissionCatalogJSON returns a copy of the canonical permission catalog.
+func PermissionCatalogJSON() []byte { return append([]byte(nil), permissionCatalogJSON...) }

package/auth/catalog_test.go

@@ -0,0 +1,53 @@
+package auth
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"testing"
+)
+
+func TestPermissionCatalogMetadataMatchesEmbeddedArtifact(t *testing.T) {
+	raw := PermissionCatalogJSON()
+	var catalog struct {
+		CatalogVersion string `json:"catalogVersion"`
+		ContentHash    string `json:"contentHash"`
+	}
+	if err := json.Unmarshal(raw, &catalog); err != nil {
+		t.Fatalf("decode permission catalog: %v", err)
+	}
+	if catalog.CatalogVersion != PermissionCatalogVersion {
+		t.Fatalf("catalog version = %q, want %q", catalog.CatalogVersion, PermissionCatalogVersion)
+	}
+	if catalog.ContentHash != "sha256:"+PermissionCatalogContentSHA256 {
+		t.Fatalf("content hash = %q", catalog.ContentHash)
+	}
+	sum := sha256.Sum256(raw)
+	if got := hex.EncodeToString(sum[:]); got != PermissionCatalogSHA256 {
+		t.Fatalf("artifact hash = %q, want %q", got, PermissionCatalogSHA256)
+	}
+}
+
+func TestPermissionCatalogIncludesVirtualizationStorageView(t *testing.T) {
+	var catalog struct {
+		Permissions []struct {
+			Key        string `json:"key"`
+			Action     string `json:"action"`
+			RiskLevel  string `json:"riskLevel"`
+			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 == "virtualization.storage.view" {
+			if permission.Action != "view" || permission.RiskLevel != "read" || permission.Status != "active" || !permission.Assignable {
+				t.Fatalf("unexpected storage permission: %#v", permission)
+			}
+			return
+		}
+	}
+	t.Fatal("virtualization.storage.view is missing")
+}