@opensoha/contracts 0.1.26 → 0.1.29

package/helmrelease/runtime/values_upgrade.go

@@ -0,0 +1,78 @@
+package runtime
+
+import (
+	"errors"
+	"fmt"
+
+	"github.com/opensoha/soha-contracts/helmrelease"
+	"helm.sh/helm/v4/pkg/action"
+	"helm.sh/helm/v4/pkg/release"
+	helmreleasev1 "helm.sh/helm/v4/pkg/release/v1"
+	"helm.sh/helm/v4/pkg/storage/driver"
+)
+
+// GuardValuesUpgradeRevision protects a single Values upgrade on a request-local Helm configuration.
+func GuardValuesUpgradeRevision(cfg *action.Configuration, upgrade *action.Upgrade, current *helmreleasev1.Release, expected int) error {
+	if expected == 0 {
+		return nil
+	}
+	if !helmrelease.ValuesExpectedRevision(expected).Valid() || current.Version != expected ||
+		(current.Info != nil && current.Info.Status.IsPending()) {
+		return helmValuesRevisionConflict()
+	}
+	// Storage.Create otherwise prunes history before it attempts to reserve the revision.
+	upgrade.MaxHistory = 0
+	cfg.Releases.Driver = valuesRevisionDriver{Driver: cfg.Releases.Driver, name: current.Name, expected: expected}
+	return nil
+}
+
+type valuesRevisionDriver struct {
+	driver.Driver
+	name     string
+	expected int
+}
+
+func (d valuesRevisionDriver) Query(labels map[string]string) ([]release.Releaser, error) {
+	items, err := d.Driver.Query(labels)
+	// Helm's preparation reads history again and can encounter a newer pending release.
+	if len(labels) != 2 || labels["name"] != d.name || labels["owner"] != "helm" {
+		return items, err
+	}
+	if errors.Is(err, driver.ErrReleaseNotFound) {
+		return nil, helmValuesRevisionConflict()
+	}
+	if err != nil {
+		return nil, err
+	}
+	latest := 0
+	for _, item := range items {
+		revision, err := release.NewAccessor(item)
+		if err != nil {
+			return nil, err
+		}
+		latest = max(latest, revision.Version())
+	}
+	if latest != d.expected {
+		return nil, helmValuesRevisionConflict()
+	}
+	return items, nil
+}
+
+func (d valuesRevisionDriver) Create(key string, item release.Releaser) error {
+	revision, err := release.NewAccessor(item)
+	if err != nil {
+		return err
+	}
+	if revision.Name() != d.name || revision.Version() != d.expected+1 {
+		return helmValuesRevisionConflict()
+	}
+	err = d.Driver.Create(key, item)
+	if errors.Is(err, driver.ErrReleaseExists) {
+		return helmValuesRevisionConflict()
+	}
+	return err
+}
+
+func helmValuesRevisionConflict() error {
+	return fmt.Errorf("%w: Helm release revision changed or is pending; refresh its values before saving", ErrConflict)
+}

package/helmrelease/runtime/values_upgrade_test.go

@@ -0,0 +1,123 @@
+package runtime
+
+import (
+	"context"
+	"errors"
+	"io"
+	"testing"
+
+	"helm.sh/helm/v4/pkg/action"
+	"helm.sh/helm/v4/pkg/chart/common"
+	chartv2 "helm.sh/helm/v4/pkg/chart/v2"
+	"helm.sh/helm/v4/pkg/kube"
+	kubefake "helm.sh/helm/v4/pkg/kube/fake"
+	"helm.sh/helm/v4/pkg/release"
+	releasecommon "helm.sh/helm/v4/pkg/release/common"
+	releasev1 "helm.sh/helm/v4/pkg/release/v1"
+	"helm.sh/helm/v4/pkg/storage"
+	"helm.sh/helm/v4/pkg/storage/driver"
+)
+
+func TestGuardValuesUpgradeRevision(t *testing.T) {
+	for _, tc := range []struct {
+		name          string
+		expected      int
+		change        bool
+		collision     bool
+		wantRevisions int
+		wantWrites    int
+	}{
+		{name: "stale before upgrade", expected: 1, wantRevisions: 2},
+		{name: "external pending revision after editor read", expected: 2, change: true, wantRevisions: 3},
+		{name: "same revision storage collision", expected: 2, collision: true, wantRevisions: 3},
+		{name: "current revision", expected: 2, wantRevisions: 3, wantWrites: 1},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			chart := &chartv2.Chart{Metadata: &chartv2.Metadata{APIVersion: "v2", Name: "app", Version: "1.0.0"}}
+			first := &releasev1.Release{Name: "app", Namespace: "test", Version: 1, Chart: chart, Info: &releasev1.Info{Status: releasecommon.StatusSuperseded}}
+			current := &releasev1.Release{Name: "app", Namespace: "test", Version: 2, Chart: chart, Info: &releasev1.Info{Status: releasecommon.StatusDeployed}}
+			winner := &releasev1.Release{Name: "app", Namespace: "test", Version: 3, Chart: chart, Info: &releasev1.Info{Status: releasecommon.StatusPendingUpgrade}, Config: map[string]any{"winner": true}}
+			history := storage.Init(driver.NewMemory())
+			for _, item := range []*releasev1.Release{first, current} {
+				if err := history.Create(item); err != nil {
+					t.Fatal(err)
+				}
+			}
+			kubeClient := &valuesUpgradeKubeClient{PrintingKubeClient: kubefake.PrintingKubeClient{Out: io.Discard}, history: history}
+			racingDriver := valuesUpgradeRaceDriver{Driver: history.Driver}
+			if tc.collision {
+				racingDriver.winner = winner
+			}
+			cfg := &action.Configuration{Releases: storage.Init(racingDriver), KubeClient: kubeClient, Capabilities: common.DefaultCapabilities}
+			upgrade := action.NewUpgrade(cfg)
+			upgrade.Namespace = current.Namespace
+			upgrade.MaxHistory = 1
+			err := GuardValuesUpgradeRevision(cfg, upgrade, current, tc.expected)
+			if tc.change {
+				if err := history.Create(winner); err != nil {
+					t.Fatal(err)
+				}
+			}
+			if err == nil {
+				_, err = upgrade.RunWithContext(context.Background(), current.Name, chart, map[string]any{"edited": true})
+			}
+			if tc.wantWrites == 0 && !errors.Is(err, ErrConflict) || tc.wantWrites > 0 && err != nil {
+				t.Fatalf("upgrade error = %v", err)
+			}
+			if kubeClient.writes != tc.wantWrites {
+				t.Fatalf("Kubernetes updates = %d, want %d", kubeClient.writes, tc.wantWrites)
+			}
+			if kubeClient.writes > 0 && !kubeClient.reservedBeforeUpdate {
+				t.Fatal("Kubernetes updated before revision 3 was reserved")
+			}
+			items, err := history.History(current.Name)
+			if err != nil || len(items) != tc.wantRevisions {
+				t.Fatalf("history contains %d revisions, want %d, err=%v", len(items), tc.wantRevisions, err)
+			}
+			if tc.change || tc.collision {
+				latest, err := history.Last(current.Name)
+				if err != nil {
+					t.Fatal(err)
+				}
+				latestRelease, ok := latest.(*releasev1.Release)
+				if !ok {
+					t.Fatalf("latest revision has unexpected type %T", latest)
+				}
+				if latestRelease.Config["winner"] != true {
+					t.Fatal("concurrent writer's Values were overwritten")
+				}
+			}
+		})
+	}
+}
+
+type valuesUpgradeRaceDriver struct {
+	driver.Driver
+	winner *releasev1.Release
+}
+
+func (d valuesUpgradeRaceDriver) Create(key string, item release.Releaser) error {
+	if d.winner != nil {
+		if err := d.Driver.Create(key, d.winner); err != nil {
+			return err
+		}
+	}
+	return d.Driver.Create(key, item)
+}
+
+type valuesUpgradeKubeClient struct {
+	kubefake.PrintingKubeClient
+	history              *storage.Storage
+	writes               int
+	reservedBeforeUpdate bool
+}
+
+func (c *valuesUpgradeKubeClient) Update(original, target kube.ResourceList, opts ...kube.ClientUpdateOption) (*kube.Result, error) {
+	c.writes++
+	latest, err := c.history.Last("app")
+	if err == nil {
+		latestRelease, ok := latest.(*releasev1.Release)
+		c.reservedBeforeUpdate = ok && latestRelease.Version == 3 && latestRelease.Info.Status == releasecommon.StatusPendingUpgrade
+	}
+	return c.PrintingKubeClient.Update(original, target, opts...)
+}

package/helmrelease/values_update.go

@@ -0,0 +1,31 @@
+package helmrelease
+
+import (
+	"encoding/json"
+	"errors"
+	"math"
+)
+
+type ValuesUpdateRequest struct {
+	Content          string                 `json:"content"`
+	ExpectedRevision ValuesExpectedRevision `json:"expectedRevision,omitempty"`
+}
+
+// ValuesExpectedRevision uses zero internally for legacy requests that omit the field.
+type ValuesExpectedRevision int
+
+func (r ValuesExpectedRevision) Valid() bool {
+	return r > 0 && r < math.MaxInt32
+}
+
+func (r *ValuesExpectedRevision) UnmarshalJSON(data []byte) error {
+	var value int
+	if err := json.Unmarshal(data, &value); err != nil {
+		return err
+	}
+	if !ValuesExpectedRevision(value).Valid() {
+		return errors.New("expectedRevision must be between 1 and 2147483646")
+	}
+	*r = ValuesExpectedRevision(value)
+	return nil
+}

package/network/README.md

@@ -57,6 +57,11 @@ for authorization, routing, firewall configuration or accounting.
   reply attribute and require NAS accounting to echo it as `sessionId` when
   available. Session commands repeat the bound `subjectId` and `deviceId` so
   the adapter can target CoA/Disconnect without querying management APIs.
+- Capability `nas-session-accounting-v1` enables the optional command target
+  `stationId`, `accountingSessionId` and `nasPortId`. For EAP-TLS, station identity
+  comes from saved authorization/accounting, never the opaque Soha device ID.
+  A runtime that cannot receive the required target binding must report
+  unsupported rather than send a command to a guessed station.
 - If a requested CoA is unsupported, issue a disconnect command when the NAS
   binding supports it; otherwise fail closed and record the unsupported
   enforcement result.
@@ -166,3 +171,32 @@ for authorization, routing, firewall configuration or accounting.
 Consumers must cover these rules with deterministic tests. Failure is
 fail-closed for control messages and bounded reject/drop-with-counter behavior
 for telemetry.
+
+## Endpoint presence and RADIUS response
+
+- `endpoint.presence.request` goes to
+  `POST /api/network-control/v1/runtimes/{runtimeId}/endpoint:presence` using the
+  enrolled endpoint's control identity and `endpoint-presence-v1` capability.
+  `bootId` identifies the protected service incarnation; a new incarnation
+  starts a new sequence and retires the previous one. A duplicate must not
+  refresh server-side liveness. UI presence never implies a healthy service.
+- `POST /api/network-control/v1/runtimes/{runtimeId}/nas:accounting` uses
+  the enrolled NAS control identity and the existing RADIUS Accounting schema.
+  The control plane checks NAS, subject, station and accounting-session binding
+  against the saved authorization before updating session evidence. The
+  separate ingest submission remains telemetry and cannot change admission.
+- A Stop remains terminal for that Core session. A reused accounting ID,
+  conflicting binding, restart after Start, or missing Start remains unknown.
+  Received time alone cannot refresh an old observation. Accounting evidence
+  cannot authorize access or prove that a VLAN/ACL was applied.
+- Persist response restrictions before delivering NAS commands. A new
+  authentication must observe every active restriction. Policy retirement
+  never removes an existing restriction, and restoration requires current
+  health plus authorization rather than replaying a previous allow decision.
+
+## Dedicated EAP certificates and native profiles
+
+- `eap.certificate.request` uses `POST /api/network-control/v1/runtimes/{runtimeId}/eap:certificate`; `eap.certificate.activate.request` uses the same prefix with `eap:activate`. Both require the endpoint control identity and `eap-profile-v1` plus `radius-eap-tls-v1`. CSR private keys stay on the endpoint. Core binds the subject and device from enrollment and ignores CSR identity extensions.
+- A dedicated EAP issuer signs only client authentication certificates with a `network-eap` URI. EAP certificates cannot authenticate control or ingest requests. Without an issuer, issuance is unavailable. Existing runtime certificates are accepted for legacy EAP only when enrollment explicitly declares `radius-eap-tls-v1`; ordinary control credentials do not imply EAP permission.
+- Issuance is idempotent per runtime/request ID and CSR. Certificates start pending and cannot grant network access. After native installation and readback, activation atomically replaces the old EAP certificate under the parent runtime credential lock. A retired or expired parent invalidates every child. Replaying an older activation cannot revive it.
+- `admission.profiles` is delivered only to `eap-profile-v1` endpoints, with exact EAP server names, CA certificates, subject and the dedicated active EAP certificate fingerprint. Configuration export, installation, 802.1X connection and actual NAS enforcement are separate results.

package/network/network-radius-accounting.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://contracts.opensoha.dev/network/network-radius-accounting.schema.json",
   "title": "OpenSoha FreeRADIUS Accounting Adapter Request",
-  "description": "A strict credential-free request converted by soha-ingest into one canonical radius.accounting event.",
+  "description": "A strict credential-free request converted by soha-ingest into telemetry. When submitted to network-control with an enrolled NAS identity, its NAS and session binding are independently verified before updating admission evidence.",
   "type": "object",
   "additionalProperties": false,
   "required": [
@@ -20,6 +20,9 @@
     "accountingSessionId": { "$ref": "#/$defs/Identifier" },
     "sessionId": { "$ref": "#/$defs/Identifier" },
     "nasId": { "$ref": "#/$defs/Identifier" },
+    "accountingDelaySeconds": { "type": "integer", "minimum": 0, "maximum": 86400 },
+    "observedVlanId": { "type": "integer", "minimum": 1, "maximum": 4094 },
+    "observedFilterId": { "type": "string", "minLength": 1, "maxLength": 128 },
     "nasPortId": { "type": "string", "minLength": 1, "maxLength": 128 },
     "userId": { "$ref": "#/$defs/Identifier" },
     "deviceId": { "$ref": "#/$defs/Identifier" },